yadflow 3.19.0-next.2 → 4.0.0-next.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yadflow",
-  "version": "3.19.0-next.2",
-  "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo, thread, reconcile). A BMAD module + 38 yad-* skills.",
+  "version": "4.0.0-next.3",
+  "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo, thread, reconcile). Plus 38 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",
   "license": "MIT",
@@ -49,9 +49,9 @@
   },
   "keywords": [
     "sdlc",
+    "adlc",
     "yad",
     "yadflow",
-    "bmad",
     "workflow",
     "cli",
     "spec-driven-development",

package/skills/sdlc/config.yaml

@@ -1,21 +1,31 @@
-# SDLC Workflow Module Configuration
-# Hand-authored custom BMAD module (format mirrors _bmad/<module>/config.yaml, v6.8.0).
-# Source of truth lives in {project-root}/skills/ and survives BMAD updates.
-
-module_name: sdlc
-module_title: "SDLC Workflow"
-methodology: gated-team-multirepo-sdlc
+# yadflow configuration
+# The source is skills/sdlc/config.yaml in the yadflow package. `yad setup` and `yad update` copy it into
+# each project as .sdlc/config.yaml, and the skills read that copy. You may edit the copy: `yad update`
+# records the hash it wrote in .sdlc/managed.json, reports an edited copy as `modified` and keeps it.
+# `yad update --overwrite-local` replaces an edited copy, after saving it beside the file as .yad-orig.
 
 # Where epic "thinking" artifacts and per-epic state live (the product repo).
 product_root: "{project-root}"
 epics_folder: "{project-root}/epics"
 
-# Project discovery (yad-discovery) — the OPTIONAL front-zero, run once per project (greenfield AND
-# brownfield). It is modelled as the reserved "epic zero" `EP-discovery` so the entire review gate +
-# PR/MR bridge + CI sync + `yad next` operate on it unchanged. A 2-step author→review chain whose
-# review binds to the whole artifact set; on approval it terminates at `discovery-done` (no Build).
-# Output: a phased roadmap (incl. MVP) that each feature epic reads (yad-epic Step 2c) — reference-only,
-# never auto-seeds epics.
+# The Foundation (E75) — the Product level, run once per product before any feature epic (greenfield AND
+# brownfield). Its own folder, `foundation/`, under the fixed id `EP-foundation`: the id keeps the `EP-`
+# prefix so the review gate, the PR/MR bridge, CI sync and `yad next` all operate on it unchanged.
+# `yad foundation new` seeds the ledger; `yad-discovery` authors the sections. A 2-step author→review
+# chain whose review binds to the required sections; on approval it terminates at `foundation-done` (no
+# Build). Its approval is REPORTED, not enforced, before feature work begins. roadmap.md is the menu of
+# features each epic reads (yad-epic / yad-analysis Step 2c) — reference-only, never auto-seeds epics.
+foundation:
+  epic_id: "EP-foundation"                             # reserved id; yad-epic/yad-analysis never pick it
+  location: "{project-root}/foundation/"               # the sections + .sdlc/ ledger + reviews/ live here
+  optional: true                                       # a team that knows what to build starts at yad-epic
+  modes: [greenfield, brownfield]                       # stack.md / repos.md are code-aware in brownfield
+  sections: [purpose.md, scope.md, mvp.md, roadmap.md, stack.md, repos.md]
+  optional_sections: [market.md, risks.md]
+
+# The OLD spelling of the Product level — the "epic zero" every release before E75 wrote. Still READ for
+# this whole major. `yad migrate --apply` converts it into `foundation/` on a local ledger; a verified
+# ledger keeps it (CI owns that ledger). A product has ONE product level: never both.
 discovery:
   epic_id: "EP-discovery"                              # reserved id; yad-epic/yad-analysis never pick it
   location: "{project-root}/epics/EP-discovery/"       # discovery artifacts + ledger live here
@@ -23,43 +33,101 @@ discovery:
   modes: [greenfield, brownfield]                       # current-state is code-aware in brownfield; competitor study in both
   artifacts: [market-research.md, competitor-analysis.md, current-state.md, feasibility.md, requirements.md, roadmap.md]
 
-# Core configuration values (inherited convention from _bmad/config.toml).
-project_name: yadflow
+# The language the skills speak in, and the language they write documents in.
 communication_language: English
 document_output_language: English
-output_folder: "{project-root}/_bmad-output"
 
 # Default dials applied to every new step (build plan §2).
+# The lifecycle, top down: three PARTS, six PHASES inside them, and the steps inside those.
+#
+# A phase is DERIVED from a step's id and is never written into `state.json` — there is nothing to
+# author here, nothing to keep in step, and no way for it to disagree with the step it describes.
+# `stepPhase` in cli/epic-state.mjs is the one definition; this block is the same table in the file
+# people read. A review gate takes the phase of the artifact it reviews, so `epic-review` is Discover.
+#
+# Release and Operate are NAMED and not built. No step, skill or gate exists for either yet.
+#
+# NOTE the word: "phase" here means one of these six. It does NOT mean the numbered development
+# phases of yadflow itself (docs/phase-N-build-plan.md), which is what "Phase 4a/4b" means elsewhere
+# in these files, nor a gate's internal merge phase.
+# The step CATALOGUE lives in code — `STEPS` in `cli/epic-state.mjs` (E4). It is the one place that
+# says what a step is: its phase, whether it authors or gates, what artifact it writes, which skill
+# runs it, and which step a gate reviews. The phase rows below mirror the `steps:` half of it and a
+# test holds the two together row for row; everything else about a step is read from the code, not
+# from here. `yad doctor` reports a project chain that disagrees with the catalogue and rewrites
+# nothing — for this whole major the FILE wins (rule 3), because the five authoring skills still
+# hand-write their `state.json` seed. E5 makes a profile seed the chain from the catalogue instead.
+lifecycle:
+  parts: [Shape, Build, Run]
+  # Lifecycle PROFILES (E5) — the route an epic takes through the steps, defined in code as
+  # `LIFECYCLE_PROFILES` (`cli/epic-state.mjs`). Three were routes the skills already seeded by hand:
+  # `classic` (the 10-step chain, `epic` first — yad-epic / yad-stub / yad-change), `analysis-first`
+  # (the 12-step chain, `analysis` before `epic` — yad-analysis) and `discovery` (the product
+  # front-zero — yad-discovery, now the OLD spelling of the Product level). `foundation` is that level
+  # as E75 writes it — `yad foundation new`. Two are the short lanes E40 added, which nobody seeded before:
+  # `chore` (4 steps, `epic` then `stories`) and `spike` (6, the analysis in front of the chore lane).
+  # Neither short lane carries an architecture gate, so neither has a contract of its own, and neither
+  # marks any step optional. Each epic RECORDS its route as `profile` in `state.json`
+  # (file shape 6); `yad epic new` writes it when it seeds the chain, and for an epic that predates the
+  # field `yad migrate` fills it in by matching the chain. The chain stays the truth — `yad doctor`
+  # compares the two. NOT the `hub.json` `profile`, which is the unrelated setup record
+  # { codebase, repo_layout, team_size }.
+  profiles: [classic, analysis-first, chore, spike, discovery, foundation]
+  # The PRODUCT level's phase (E75) — a ladder of its own, run once per product before any epic, and
+  # part of no Part. `discovery` is listed because it is the old spelling of the same level.
+  product_phases:
+    - { id: foundation, name: Foundation, level: product, built: true, steps: [foundation, discovery] }
+  phases:
+    - { id: discover, name: Discover, part: Shape, built: true,  steps: [analysis, epic] }
+    - { id: design,   name: Design,   part: Shape, built: true,  steps: [architecture, ui-design] }
+    - { id: plan,     name: Plan,     part: Shape, built: true,  steps: [stories, test-cases] }
+    - { id: build,    name: Build,    part: Build, built: true,  steps: [spec, tasks, implement, checks, engineer-review] }
+    - { id: release,  name: Release,  part: Run,   built: false, steps: [] }   # E32 builds it
+    - { id: operate,  name: Operate,  part: Run,   built: false, steps: [] }   # E33 builds it
+  # `currentStep` markers that are NOT steps: they never appear in `steps[]` and have no phase.
+  sentinels: [ready-for-build, backfill-pending, backfill-done, discovery-done, foundation-done]
+
 defaults:
-  assistance: review          # none | review | heavy
-  automation: human_approve   # human_approve | machine_advance
-  # Shape steps (discovery [optional front-zero], analysis [optional], epic, architecture,
+  # The two dials: who does the work, and who moves it forward. Renamed in shape 4; BOTH names are
+  # written on every step and the OLD one is still the one read, so an older CLI and the skills that
+  # hand-write state.json keep working. See docs/migrations/shape-4.md.
+  assistance: review          # none | review | heavy         (old name — still authoritative)
+  driver: pair                # human | pair | agent          (new name, shape 4)
+  automation: human_approve   # human_approve | machine_advance  (old name — still authoritative)
+  advance: human              # human | auto                  (new name, shape 4)
+  # Shape steps (foundation [optional, the Product level — discovery is its old spelling], analysis [optional], epic, architecture,
   # ui-design [optional — skippable N/A for UI-less epics via `yad skip <epic> ui-design --reason "<why>"`],
-  # stories, test-cases) are locked to human_approve and may NOT be set to machine_advance in this
+  # stories, test-cases) are locked to `advance: human` and may NOT be set to `advance: auto` in this
   # version (build plan §1, §8.7).
   shape_steps_locked: true
   # Each Shape authoring step opens its own branch at the start of the step (the <step> is the step id:
   # discovery | analysis | epic | architecture | ui-design | stories | test-cases). Git/greenfield-safe; distinct
-  # from the verified ledger's review branch (hub.artifact_branch). See yad-epic/references/state-schema.md.
+  # from the verified ledger's review branch (product.artifact_branch). See yad-epic/references/state-schema.md.
   shape_authoring_branch: "<step>/EP-<slug>"
 
 # Team review gate defaults (build plan §3 piece 2, §4).
 review_gate:
-  default_reviewers: 1          # non-owner reviewers required (in addition to 1 owner) => owner + 1 reviewer
+  # `default_reviewers` is no longer read since E62 (the owner + reviewer role rule is gone). A team gate
+  # needs 1 approval from someone other than the author (base 1); the full count adds the risk step
+  # below, which is advisory. E72 caps that count at the active people less one and reports it;
+  # only the base holds a gate.
+  default_reviewers: 1          # legacy, not read since E62
   # Solo mode (a lone developer): a relaxed, opt-in safety guarantee, recorded per-project in
   # .sdlc/hub.json (`solo: true`). On GitHub you CANNOT approve your own PR, so requiring an approval
   # would deadlock a solo user. Solo waives the APPROVAL requirement only — the review PR/MR and its
   # MERGE stay (CI still runs on the PR, and the merge is what advances the step). Net: the gate passes
   # on `merged + all comment threads resolved`, no approval needed. NOT a default; team gates are
   # unchanged. (Branch protection must not "require approvals", or the solo dev's own merge is blocked —
-  # `yad doctor` warns when it does.)
+  # `yad doctor` warns when it does.) Switch it with `yad mode solo --reason "<why>"` / `yad mode team` (E10),
+  # which records who, when and why, and writes `mode: solo|team` beside `solo`; a gate that passes in solo
+  # mode records `waived: "solo"` on its closing record.
   solo: false
-  escalate_when: [contract, auth, payments]   # escalate to domain owners
-  # PR-driven automation (the `yad gate` CLI). With a hub platform, the review rides the per-step
+  escalate_when: [contract, auth, payments]   # risk tags that add a risk step (contract +2, auth/payments +1; the largest, never the sum)
+  # PR-driven automation (the `yad gate` CLI). With a Product platform, the review rides the per-step
   # PR/MR: `yad gate sync` maps platform reviews/threads into the file ledger and the step
-  # AUTO-ADVANCES on merge, once (a) the reviewer rule is met, (b) every comment thread is resolved,
+  # AUTO-ADVANCES on merge, once (a) the approval rule is met, (b) every comment thread is resolved,
   # and (c) the review PR/MR is merged. The merge is the human approval act, so Shape steps still never
-  # machine_advance. The file ledger stays the source of truth; no platform / no gh|glab => local.
+  # `advance: auto`. The file ledger stays the source of truth; no platform / no gh|glab => local.
   advance_on: merge             # merge of the approved, fully-resolved review PR advances the step
   revoke_on: artifact-change    # re-hash the artifact (contract surface for architecture); a changed
                                 # hash drops the bound approvals so reviewers re-approve. NOT per-commit.
@@ -122,10 +190,10 @@ build:
   # Shape artifacts can never go stale), and reconcile-debt (a hotfix's ship-first debt blocks the next
   # change on its thread until paid). See the `change:` block below.
   gates: [spec-link, contract-check, build-test-lint, lineage-check, epic-open, reconcile-debt]
-  # Pattern gates — commit subject + PR/MR title + PR/MR template-usage. Profile-aware (code|hub): code
-  # repos validate the Conventional-Commits / task-PR conventions; the product hub validates its
-  # artifact-review conventions (review/EP-<slug>/<artifact>, the hub PR template). verified-commits is
-  # the separate security gate (signature + roster-known author). All blocking in CI; both repos + hub.
+  # Pattern gates — commit subject + PR/MR title + PR/MR template-usage. Profile-aware (code|hub|product): code
+  # repos validate the Conventional-Commits / task-PR conventions; the Product validates its
+  # artifact-review conventions (review/EP-<slug>/<artifact>, the Product PR template). verified-commits is
+  # the separate security gate (a platform-Verified signature only; no author allowlist since E62). All blocking in CI; both repos + Product.
   pattern_gates: [commit-message, pr-title, pr-template]
   ci_platforms: [github, gitlab]   # both wired from skills/yad-checks/templates/; GitHub is this product repo's platform
   contract_surface_glob: "specs/*/contracts/**"   # the repo's quoted contract slice; a diff here needs Contract-Change + a re-locked contract
@@ -133,10 +201,10 @@ build:
   pr_templates:
     github: ".github/pull_request_template.md"
     gitlab: ".gitlab/merge_request_templates/Default.md"
-    hub:                                # Shape artifact-review PR/MR on the product hub (yad-pr-template repo:hub)
+    hub:                                # Shape artifact-review PR/MR on the Product (yad-pr-template repo:hub)
       github: ".github/pull_request_template.md"
       gitlab: ".gitlab/merge_request_templates/Default.md"
-  risk_levels: [low, medium, high]   # high (or a contract/auth/payments surface) routes to domain owners (yad-review-gate escalation)
+  risk_levels: [low, medium, high]   # high +1 / a contract surface +2 to the approver count (advisory; yad-review-gate count)
   # Step E (yad-engineer-review) — AI review (advisory) + engineer review (the human gate) + merge.
   ai_review: coderabbit            # advisory first pass; never the authority (.coderabbit.yaml)
   # Append-only ship ledger (Build analogue of approvals.json), stored shard-then-fold: writers add one
@@ -155,15 +223,15 @@ build:
     promote: yad-stub   # `yad-backfill promote EP-<slug>` flips a brownfield stub epic (change.stub) to a real, verified feature epic once its spec is approved
 
 # Code context (yad-connect-repos) — the front/"brain" phases are made code-aware. Code repos are
-# connected to the product hub once (or any time a new repo is added), and an AI-readable picture of
+# connected to the Product once (or any time a new repo is added), and an AI-readable picture of
 # each is cached so epic/architecture/ui/stories consider what already exists in the code. The product
-# repo is the Shape phase TOOLCHAIN HUB: repomix (and Impeccable) are installed/run here and target the
+# repo is the Shape phase TOOLCHAIN: repomix (and Impeccable) are installed/run here and target the
 # connected code repos by path — code repos need no install for this. (The Build CI gates are the
 # exception: they live INSIDE each code repo and run in that repo's CI — see build.gates above.)
 code_context:
   registry: "{project-root}/.sdlc/repos.json"        # project-wide repo registry (NOT per-epic)
   cache_dir: "{project-root}/.sdlc/code-context"      # per-repo pack.md + code-map.md live here
-  tools: [repomix, impeccable]                        # Shape phase toolchain, installed in the product hub
+  tools: [repomix, impeccable]                        # Shape phase toolchain, installed in the Product
   pack_flags: "--compress --include-logs --style markdown"   # reuse backfill flags; Secretlint by default
   staleness: head-sha                                 # stale when a repo's HEAD != registry syncedHead
   refresh: human                                      # a stale repo is a HUMAN decision: Shape phase
@@ -251,42 +319,38 @@ docs:
   # tokens — publishing runs as the LOCAL user's own gh/glab or the platform CI. Idempotent, refreshable.
   auth: user
 
-# Hub platform + Shape review bridge (yad-connect-repos `detect-hub`; yad-review-gate + yad-hub-bridge).
-# The product hub is itself a git repo on a platform. With a verified ledger, the Shape review/
-# comment/approval cycle runs through a real PR/MR on the hub: a review PR is opened per artifact, reviewers
+# Product platform + Shape review bridge (yad-connect-repos `detect-hub`; yad-review-gate + yad-hub-bridge).
+# The Product is itself a git repo on a platform. With a verified ledger, the Shape review/
+# comment/approval cycle runs through a real PR/MR on the Product: a review PR is opened per artifact, reviewers
 # approve/comment on the platform (their own gh/glab auth — NO stored tokens), and `yad-review-gate action: sync`
 # pulls that state into the file ledger (approvals.json/reviews/*.md) and runs the UNCHANGED gate predicate.
 # The file ledger stays the source of truth. Degrades to the local gate when there is no platform / no CLI.
-hub:
-  config: "{project-root}/.sdlc/hub.json"             # hub platform + reviewer roster (committed, like repos.json)
-  pr_ledger: "{project-root}/epics/EP-<slug>/.sdlc/hub-prs.json"   # per-step review-PR record (sibling of approvals.json)
+# Renamed from `hub:` (shape 3). Nothing in the engine parses this file — the skills read it — so
+# there is no compatibility shim here: an older project simply still says `hub:`, and the skills name
+# both. The paths below carry both names too, for the same reason the files do.
+product:
+  config: "{project-root}/.sdlc/product.json"          # product platform (committed, like repos.json); no roster since E62
+  config_legacy: "{project-root}/.sdlc/hub.json"       # the older name, still written and still the one READ this major
+  pr_ledger: "{project-root}/epics/EP-<slug>/.sdlc/product-prs.json"       # per-step review-PR record (sibling of approvals.json)
+  pr_ledger_legacy: "{project-root}/epics/EP-<slug>/.sdlc/hub-prs.json"    # the older name — written alongside it AND still the one read, like config_legacy
   bridge: true                                         # master enable; false => local Shape gates everywhere
-  platforms: [github, gitlab]                          # detected from the hub's own `git remote get-url origin`
+  platforms: [github, gitlab]                          # detected from the Product's own `git remote get-url origin`
   artifact_branch: "review/EP-<slug>/<artifact-base>"  # branch a review PR is opened on, per artifact
-  # roster (in hub.json) maps a platform login -> yad name + role; domain-owners are DERIVED from
-  # repos.json (a roster name that equals a repo's domain_owner owns that repo's domain) — never duplicated.
+  # No roster since E62: yadflow stores no people. Approvals record the platform login as `approver`. A
+  # `roster` in hub.json or `domain_owner(s)` in repos.json left by an older release decides nothing (the
+  # roster's name -> login pairs only let the first sync recognise older approvals).
 
-# Phase 4 (automation) — the SECOND dial made real. Until Phase 4 nothing read this dial; the
-# orchestrator (yad-run) now does. Governing rule: automation is EARNED per step, with trust-log
-# evidence, and is reversible in one move (phase-4-build-plan.md §"one principle"). Shape steps are
-# never listed in back_steps and can never be flipped — the engineer keeps authority over decisions.
+# Phase 4 (automation) — the SECOND dial made real: the orchestrator (yad-run) reads it and acts. Since
+# E34 the dial is SET, not earned. `yad dial` sets it — a Build lane step's dial in build-state, a Shape
+# author step's for the whole project in `.sdlc/automation.json` — and shows the step's run record as
+# advice, never as a refusal. A review gate is never auto (rule 1).
+# The KILL SWITCH is not in this file any more: `yad kill --reason "<why>"` / `yad unkill` record it in
+# `.sdlc/automation.json`. This file is installed and hash-managed by `yad update`, so a value edited here
+# stops the file being updated — and nothing reads `kill_switch` now. `yad doctor` fails on one left `true`.
 automation:
   # The only steps that MAY be automated, safest-end first (phase-4-build-plan.md build order).
-  # Phase 4a ships the engine + earns `checks` (Step B). `tasks`/`implement` advance are Phase 4b.
   back_steps: [spec, tasks, implement, checks]
-  default: human_approve            # every Build step starts manual; machine_advance must be earned
-  # A Build step is a CANDIDATE for machine_advance only once its trust-log slice clears this bar.
-  # "It seems fine" is not evidence (phase-4-build-plan.md §"Explicitly NOT").
-  trust_threshold:
-    min_runs: 5                     # at least this many recorded runs at the step
-    min_approved_unchanged: 0.8     # >= this fraction "approved-unchanged" over those runs
-  # Hard lock — the dial-setter REFUSES machine_advance for these, regardless of trust evidence.
-  # The Shape authoring steps (already locked:true in state.json; analysis is optional) + the human
-  # merge gate.
-  locked_steps: [discovery, analysis, epic, architecture, ui-design, stories, test-cases, engineer-review]
-  # Kill switch (phase-4-build-plan.md §Safety): true => every step forced to human_approve
-  # system-wide, no per-step edits. One line, instantly reversible. Toggle via `yad-run action: kill`.
-  kill_switch: false
+  default: human_approve            # = `advance: human`. Every lane step starts manual; `yad dial` turns one to auto
 
 # Phase 6 (post-lock change management) — FEATURE THREADS. After the contract locks and code ships, a
 # change must not MUTATE a locked artifact (that destroys the audit trail and the lock). Instead every
@@ -297,18 +361,31 @@ automation:
 # docs/phase-6-build-plan.md and skills/yad-change. yad-defects/yad-timeline render it; yad-reconcile
 # (read-only, like yad-docs-sync) flags orphan/drift; the three gates above enforce it.
 change:
-  # The kind of an epic (epic.md frontmatter `kind:`). `feature` is the genesis (default when absent).
-  kinds: [feature, change, defect, hotfix]
+  # The work-item TYPE (epic.md frontmatter). Two names carry it: `kind:` is the original and is still
+  # the one that is READ; `type:` is the same value under the name from shape 5 on. Write both.
+  # `feature` and `chore` are the genesis types — they may stand alone with no `parent:`.
+  kinds: [feature, change, defect, hotfix, chore]
+  types: [feature, change, defect, hotfix, chore]     # the same list under the newer name
+  genesis_types: [feature, chore]                     # may have no `parent:` (cli isGenesisType)
+  # GROUPING. `theme:` on epic.md is a FREE tag — one word or short phrase shared by every epic that
+  # belongs together. It is what stands in for a rung above the Epic: the ladder is
+  # Product -> Epic -> Story -> Task, and grouping is a label rather than a level. There is no list of
+  # allowed themes and nothing to register, it is optional, and it is ONE tag (`theme: [a, b]` reads
+  # as no theme at all). It lives only in epic.md — no copy in state.json, so no file shape changed.
+  # Any language. `yad doctor` reports one theme spelled two ways (theme:variants), because two
+  # spellings group as two, and a `#` inside the value (theme:commented), because these frontmatter
+  # readers keep the whole rest of the line and the printed `#…` is only decoration.
+  grouping_frontmatter: [theme]
   # Triage DEPTH (yad-change auto-proposes, human confirms) -> which Shape steps are re-authored vs
   # inherited. defect-fix re-authors stories+test-cases only; contract-surface re-authors architecture
-  # and RE-LOCKS (a new hash routes architecture-review through the contract escalation, as today).
+  # and RE-LOCKS (a new hash sends architecture-review back through review, with the contract risk step, as today).
   depths: [defect-fix, behavioral-no-surface, contract-surface, new-capability]
   thread_id: genesis_epic_id            # the thread id = the genesis epic's id (never renamed -> stablest anchor)
   # Lineage frontmatter added to epic.md (mirrors the design:/testing: enrichment blocks — the locked
   # state.json step shape is untouched). `thread` is a DERIVED cache (authoritative = walk `parent` to
   # the root); a mismatch is detectable corruption (yad doctor threadChecks). defect/hotfix also carry
   # origin/severity/escape_stage/root_cause for the quality report (yad-defects).
-  lineage_frontmatter: [kind, thread, parent, inherits, supersedes, origin, severity, escape_stage, root_cause]
+  lineage_frontmatter: [kind, type, thread, parent, inherits, supersedes, origin, severity, escape_stage, root_cause]
   artifact_bases: [epic, architecture, contract, ui-design, stories, test-cases]   # what `inherits` may list
   severity: [sev1, sev2, sev3, sev4]    # defect/hotfix severity
   # Per-change-epic ledgers (siblings of approvals.json; the locked state.json shape is untouched).
@@ -326,14 +403,16 @@ change:
   seal_on: all-stories-shipped
   # Brownfield stub anchor (yad-stub): an already-built feature with NO epic can't be a change parent
   # (yad-change requires a real parent; lineage-check rejects a missing one). yad-stub mints the smallest
-  # real thread anchor — a genesis epic.md (kind:feature, thread:self) marked `stub: backfill-pending` /
-  # `verified: false`, with a state.json carrying `kind: stub` + `currentStep: backfill-pending`. A change
+  # real thread anchor — a genesis epic.md (kind+type: feature, thread:self) marked `stub:
+  # backfill-pending` / `verified: false`, with a state.json carrying the lifecycle marker `kind: stub`
+  # BESIDE the work-item `type: feature` + `currentStep: backfill-pending`. A change
   # threaded off a stub inherits only what exists (boundHash: null for the undocumented surface bases) and
   # writes NO pointer-lock; change.json records `parentStub: true`. `yad-backfill promote` flips the stub
   # to verified (clears the marker), at which point contract protection begins for the thread.
   stub:
     marker: backfill-pending            # epic.md `stub:` value while the anchor is un-promoted
-    state_kind: stub                    # state.json top-level `kind` + `currentStep: backfill-pending` sentinel
+    state_kind: stub                    # state.json top-level `kind` + `currentStep: backfill-pending` sentinel.
+                                        # A LIFECYCLE marker, not the work-item type — a stub carries both.
     allow_stub_parent: true             # a change/defect MAY thread off an un-promoted stub (default on)
     promote_by: yad-backfill            # `yad-backfill promote EP-<slug>` documents + flips the stub to real
   hotfix:

package/skills/sdlc/module-help.csv

@@ -1,39 +1,39 @@
 module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
-SDLC Workflow,yad-discovery,Project Discovery,DI,"Optional front-zero (once per project, greenfield AND brownfield): with the analyst + pm run market research, a competitor study, a feasibility study, and (brownfield) a current-state study, then distil functional + non-functional requirements and a phased roadmap (MVP and beyond) under the reserved EP-discovery. roadmap.md becomes the menu of features each yad-epic reads. Never auto-advances.",,{idea: one-line product idea} {mode: greenfield|brownfield},0-front,,yad-review-gate,false,epics/EP-discovery/,market-research.md competitor-analysis.md current-state.md feasibility.md requirements.md roadmap.md state.json
+SDLC Workflow,yad-discovery,Foundation,DI,"The Foundation — the Product level, once per product before any epic (greenfield AND brownfield). After yad foundation new seeds the ledger, with the analyst + pm write the sections into foundation/ (EP-foundation): purpose, market (optional), scope (what it is and is not), MVP, roadmap, stack, repos, risks (optional). roadmap.md becomes the menu of features each yad-epic reads. Its approval is reported, not enforced, before feature work. Never auto-advances.",,{idea: one-line product idea} {mode: greenfield|brownfield},0-front,,yad-review-gate,false,foundation/,purpose.md market.md scope.md mvp.md roadmap.md stack.md repos.md risks.md state.json
 SDLC Workflow,yad-analysis,Author Analysis,AN,"Optional Shape step: with the analyst pressure-test a feature idea and write the discovery brief into analysis.md. Assigns the EP-<slug> ID and seeds .sdlc state (the chain that puts analysis before epic). If skipped, the epic step does this shaping inline. Never auto-advances.",,{idea: one-line feature idea},1-front,,yad-review-gate,false,epics/EP-<slug>/,analysis.md state.json
 SDLC Workflow,yad-epic,Author Epic,AE,"Shape step 1: shape an idea with analyst then pm into epic.md; assign EP-<slug> ID and seed .sdlc state. Never auto-advances.",,{idea: one-line feature idea},1-front,,yad-review-gate,true,epics/EP-<slug>/,epic.md state.json
-SDLC Workflow,yad-review-gate,Team Review Gate,RG,"Reusable review+approve gate for all five reviews. Shares an artifact for review, records comments and approvals as files, enforces owner + 1 reviewer (escalates on contract/auth/payments; per-repo routing for stories), advances state only when approved.",,{artifact: file under the epic} {action: open|comment|approve|advance},1-front,,,true,epics/EP-<slug>/reviews/,reviews/*.md approvals.json state.json
+SDLC Workflow,yad-review-gate,Team Review Gate,RG,"Reusable review+approve gate for every Shape review. Shares an artifact for review, records comments and approvals as files, enforces at least 1 approval from someone other than the author (contract/auth/payments add a risk step to the count, capped at the active people less one and advisory), advances state only when approved.",,{artifact: file under the epic} {action: open|comment|approve|advance},1-front,,,true,epics/EP-<slug>/reviews/,reviews/*.md approvals.json state.json
 SDLC Workflow,yad-review-companion,Review Companion,RC,"Fun, easy, transparent review companion for the review gates (Shape gate AND Build code PR). Generates a 60-sec AI trailer of what changed and where the risk is, deals swipe-through review cards, and runs a grounded chat where a reviewer's questions become the review record — then records an engagement signal on the approval (verified vs none) and posts a friendly public @-mention nudge on a bare rubber-stamp. Companion comments carry a noblock marker so they never hold the gate. Soft by default (visible, not impossible); gates only when hub.review.requireEngagement. Never auto-advances.",,{epic: EP-<slug>} {artifact} | {repo} {pr} {action: trailer|cards|chat|nudge},1-front,,,false,epics/EP-<slug>/reviews/ | code PR,trailer/cards/chat (platform) approvals.json engagement
 SDLC Workflow,yad-pair-review,Pair Review,PV,"The guided, two-way, teaching pair-review walkthrough — the AI-driven 5th companion face (Shape gate AND Build code PR). The human opens a PR/MR with an AI session and the AI walks them through the change one stop at a time (highest-risk first), gives comprehensive context per change, then asks a Socratic question; the human answers and asks back until BOTH declare satisfied. Doubles as a learning session: demonstrates a transferable review method, scores the engineer, and records review-skill growth in the local-only yad-learn ledger (rolled up by yad status). Soft and additive — NEVER blocks; rides the engagement signal and surfaces genuine concerns as normal blocking comments. Never auto-advances.",,{epic: EP-<slug>} {artifact} | {repo} {pr} {member} {action: walkthrough|record|rubric},3-build,yad-review-companion,,false,epics/EP-<slug>/reviews/ | code PR | epics/EP-<slug>/learning/ (local-only),pair session (platform) learning-records.json learning/<member>--review-<pr>.md
 SDLC Workflow,yad-architecture,Author Architecture,AA,"Shape step 3: with the architect author architecture.md and the locked contract.md; hash-lock the contract surface. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,architecture.md contract.md contract-lock.json state.json
 SDLC Workflow,yad-ui,Author UI Design,AU,"Shape step 5: with the ux-designer author ui-design.md and DESIGN.md, driving Impeccable slash-commands when installed. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,ui-design.md DESIGN.md state.json
 SDLC Workflow,yad-stories,Author Stories,AS,"Shape step 7: with the pm break the epic into repo-tagged stories with stable EP-<slug>-S0N IDs, one file each under stories/. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/stories/,stories/EP-<slug>-S0N.md state.json
-SDLC Workflow,yad-test-cases,Author Test Cases,TC,"Shape step 9 (PARALLEL, non-blocking): opens when the stories gate passes — the epic is already ready-for-build, so Build can start at the same time the tester works here. With the test architect (Murat) author test-cases.md covering the approved stories, and — when a testing tool is connected (.sdlc/testing.json) — generate/link the actual automation tests in it, recording test-links.json; otherwise produce the test-case artifact only. Its review never moves currentStep off ready-for-build. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,test-cases.md test-links.json state.json
-SDLC Workflow,yad-connect-repos,Connect Code Repos,CR,"Setup/maintenance: connect code repos to the product hub so the Shape/brain phases are code-aware. Registers each repo (GitHub or GitLab, local-user auth, no stored tokens) in .sdlc/repos.json and caches a Repomix pack + a lightweight code-map (existing endpoints/events/data-models/modules, secret-scanned). Idempotent and refreshable; staleness tracked by HEAD sha. yad repo refresh --push publishes the refreshed code-maps + registry to the hub default branch as a chore(hub): sync code-context [skip ci] audit commit. Run at setup or any time a new repo is added. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {repo: <name>} {path: <path-or-absolute>} {git_url: <ssh-or-https>} {domain_owner: <who>},0-setup,,yad-sync-repos,false,.sdlc/,repos.json code-context/<repo>/pack.md code-context/<repo>/code-map.md
+SDLC Workflow,yad-test-cases,Author Test Cases,TC,"Shape step 9 (PARALLEL, non-blocking): opens when the stories gate passes — the epic is already ready-for-build, so Build can start at the same time the tester works here. With the test architect author test-cases.md covering the approved stories, and — when a testing tool is connected (.sdlc/testing.json) — generate/link the actual automation tests in it, recording test-links.json; otherwise produce the test-case artifact only. Its review never moves currentStep off ready-for-build. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,test-cases.md test-links.json state.json
+SDLC Workflow,yad-connect-repos,Connect Code Repos,CR,"Setup/maintenance: connect code repos to the Product so the Shape/brain phases are code-aware. Registers each repo (GitHub or GitLab, local-user auth, no stored tokens) in .sdlc/repos.json and caches a Repomix pack + a lightweight code-map (existing endpoints/events/data-models/modules, secret-scanned). Idempotent and refreshable; staleness tracked by HEAD sha. yad repo refresh --push publishes the refreshed code-maps + registry to the Product default branch as a chore(hub): sync code-context [skip ci] audit commit. Also drafts each code repo's .sdlc/risk-map (a level per directory, no names) by reading the code, marked guessed for a person to confirm. Run at setup or any time a new repo is added. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {repo: <name>} {path: <path-or-absolute>} {git_url: <ssh-or-https>},0-setup,,yad-sync-repos,false,.sdlc/,repos.json code-context/<repo>/pack.md code-context/<repo>/code-map.md
 SDLC Workflow,yad-sync-repos,Sync Connected Repos,SR,"Setup/maintenance: bring every connected repo up to date in one shot — switch each repo in .sdlc/repos.json to its default_branch and fast-forward it from origin (local-user git, no stored tokens). Working-tree only; never a gate and never writes the registry. A dirty repo is skipped and reported (never overwritten); a diverged branch is left for manual resolution (fast-forward only). After pulling, a repo's cached pack goes stale — points the human at yad repo refresh.",,{action: sync} {repo: <name>},0-setup,yad-connect-repos,yad-connect-design,false,,(none — working-tree only)
-SDLC Workflow,yad-connect-design,Connect Design Tool,CD,"Setup/maintenance: connect a design tool (Figma-first, pluggable) to the product hub so the UI design step can materialize the actual feature design (mobile screens / web pages) inside it, alongside ui-design.md + DESIGN.md. Records the tool + project/file references in .sdlc/design.json (local-user / MCP-session auth, no stored tokens), detecting whether a design-tool MCP is available and degrading to markdown-only when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: figma|pencil|none} {project_url: <team/project/file url>} {files: {web,mobile}},0-setup,,yad-ui,false,.sdlc/,design.json
-SDLC Workflow,yad-connect-testing,Connect Testing Tool,CT,"Setup/maintenance: connect a testing tool (Playwright-first, pluggable) to the product hub so the test-cases step can implement the actual automation tests in it, alongside test-cases.md. Records the tool + project/suite references in .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 absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: playwright|cypress|pytest|none} {project_url: <project/config reference>} {suites: {<repo>}},0-setup,,yad-test-cases,false,.sdlc/,testing.json
+SDLC Workflow,yad-connect-design,Connect Design Tool,CD,"Setup/maintenance: connect a design tool (Figma-first, pluggable) to the Product so the UI design step can materialize the actual feature design (mobile screens / web pages) inside it, alongside ui-design.md + DESIGN.md. Records the tool + project/file references in .sdlc/design.json (local-user / MCP-session auth, no stored tokens), detecting whether a design-tool MCP is available and degrading to markdown-only when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,"{action: connect|refresh|list|disconnect} {tool: figma|pencil|none} {project_url: <team/project/file url>} {files: {web,mobile}}",0-setup,,yad-ui,false,.sdlc/,design.json
+SDLC Workflow,yad-connect-testing,Connect Testing Tool,CT,"Setup/maintenance: connect a testing tool (Playwright-first, pluggable) to the Product so the test-cases step can implement the actual automation tests in it, alongside test-cases.md. Records the tool + project/suite references in .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 absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: playwright|cypress|pytest|none} {project_url: <project/config reference>} {suites: {<repo>}},0-setup,,yad-test-cases,false,.sdlc/,testing.json
 SDLC Workflow,yad-connect-learning,Connect Learning Tool,CL,"Setup/maintenance: connect a learning/tutoring tool (DeepTutor-first, pluggable) so the cross-cutting learning layer can tutor any team member, at any SDLC stage, in the context of what is being built. Records the tool + an optional grounded knowledge base in .sdlc/learning.json (local-user auth, no stored tokens), detecting whether the DeepTutor CLI is on PATH (a subprocess like Repomix, not an MCP) and degrading to harness-native tutoring when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: deeptutor|none} {kb: <name>} {ground: true|false},0-setup,,yad-learn,false,.sdlc/,learning.json
-SDLC Workflow,yad-learn,Learn (Tutor),LN,"Cross-cutting learning layer: at ANY SDLC stage a team member can ask to learn a concept and be tutored in the context of what the team is building. Routes to the connected learning tool (.sdlc/learning.json, DeepTutor-first) grounded in the project knowledge base, or degrades to harness-native tutoring (the harness model reading the artifacts). Renders a tutorial artifact and appends to a per-member learning ledger kept LOCAL-ONLY (gitignored, never committed/pushed to the hub or any code repo) so it stays a private, personal skills log (yad-status rolls up the local records). Purely opt-in — never blocks a gate, never touches epic state, approvals, or the contract lock.",,{concept: <idea>} {context: <focus>} {epic: EP-<slug>} {stage: <sdlc stage>} {member: <who>} {mode: explain|deep|quiz} {action: learn|list|complete},,,,,false,epics/EP-<slug>/,learning-records.json learning/<member>--<concept>.md
+SDLC Workflow,yad-learn,Learn (Tutor),LN,"Cross-cutting learning layer: at ANY SDLC stage a team member can ask to learn a concept and be tutored in the context of what the team is building. Routes to the connected learning tool (.sdlc/learning.json, DeepTutor-first) grounded in the project knowledge base, or degrades to harness-native tutoring (the harness model reading the artifacts). Renders a tutorial artifact and appends to a per-member learning ledger kept LOCAL-ONLY (gitignored, never committed/pushed to the Product or any code repo) so it stays a private, personal skills log (yad-status rolls up the local records). Purely opt-in — never blocks a gate, never touches epic state, approvals, or the contract lock.",,{concept: <idea>} {context: <focus>} {epic: EP-<slug>} {stage: <sdlc stage>} {member: <who>} {mode: explain|deep|quiz} {action: learn|list|complete},anytime,,,false,epics/EP-<slug>/,learning-records.json learning/<member>--<concept>.md
 SDLC Workflow,yad-spec,Author Spec,SP,"Build Step A: for one ready-for-build story and one of its repos, run the heavy Spec Kit ceremony once (specify→clarify→plan→analyze→checklist→tasks) inside that code repo, writing specs/<story-id>/ in Spec Kit's layout (drives /speckit.* when installed, else hand-authors and records speckit: not-installed). References the locked contract; never re-invents the surface. Writes link.md back to the story. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <one of story.repos>},3-build,yad-review-gate,,false,demo-repos/<repo>/specs/<story-id>/,spec.md research.md data-model.md contracts/ plan.md tasks.md link.md
 SDLC Workflow,yad-implement,Implement Task,IM,"Build Step B: with the dev lens, implement ONE atomic task from a story's tasks.md as a small diff (<=3 files) on its own branch feat/<story>-<task>-<slug> in the code repo. Diff stays inside the task's declared files (flag and STOP if it grows beyond them). Commit ends with a Task: <story>-<task> trailer; add Contract-Change: yes only when the locked contract surface is touched (routes back to the architecture gate). Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <one of story.repos>} {task: T0N},3-build,yad-spec,,false,demo-repos/<repo>/,branch+commit per atomic task
-SDLC Workflow,yad-checks,Check Gates,CK,"Build Step C: wire and run the production-safety CI gates on a code repo (and product hub) — spec-link (every change links a real story/spec via its Task trailer), contract-check (a contract-surface change without Contract-Change + an updated re-locked contract FAILS and routes back to the architecture gate), build/test/lint, verified-commits (signed + roster-known authors), and the pattern gates commit-message / pr-title / pr-template (profile-aware code|hub). CI-agnostic bash invoked by GitHub Actions and GitLab CI. Blocking in CI; the human still owns the merge. Never auto-advances.",,{repo: <one of an epic's repos | hub>} {action: wire|run} {base: target branch},3-build,yad-implement,,false,demo-repos/<repo>/,checks/*.sh .github/workflows/yad-checks.yml .gitlab-ci.yml
-SDLC Workflow,yad-pr-template,PR/MR Template,PT,"Build Step D: detect a code repo's platform and commit the matching PR/MR template (.github/pull_request_template.md or .gitlab/merge_request_templates/Default.md) with an Impact & Risk block. A high risk level (or a touched contract/auth/payments surface) routes the review to domain owners — the same escalation yad-review-gate applies. Ships the routing helper risk-route.sh plus the pattern-gate scripts pr-title.sh and pr-template.sh (used by yad-checks). Never auto-advances.",,{repo: <one of an epic's repos | hub>} {action: wire|route} {body: PR description file},3-build,yad-checks,,false,demo-repos/<repo>/,.github/pull_request_template.md .gitlab/merge_request_templates/Default.md checks/risk-route.sh checks/pr-title.sh checks/pr-template.sh
+SDLC Workflow,yad-checks,Check Gates,CK,"Build Step C: wire and run the production-safety CI gates on a code repo (and Product) — spec-link (every change links a real story/spec via its Task trailer), contract-check (a contract-surface change without Contract-Change + an updated re-locked contract FAILS and routes back to the architecture gate), build/test/lint, verified-commits (every commit carries a platform-Verified signature), and the pattern gates commit-message / pr-title / pr-template (profile-aware code|hub). CI-agnostic bash invoked by GitHub Actions and GitLab CI. Blocking in CI; the human still owns the merge. Never auto-advances.",,{repo: <one of an epic's repos | hub>} {action: wire|run} {base: target branch},3-build,yad-implement,,false,demo-repos/<repo>/,checks/*.sh .github/workflows/yad-checks.yml .gitlab/ci/yad-checks.yml
+SDLC Workflow,yad-pr-template,PR/MR Template,PT,"Build Step D: detect a code repo's platform and commit the matching PR/MR template (.github/pull_request_template.md or .gitlab/merge_request_templates/Default.md) with an Impact & Risk block. A high risk level (or a touched contract surface) raises the approver count — the same count yad-review-gate prints. Ships the routing helper risk-route.sh plus the pattern-gate scripts pr-title.sh and pr-template.sh (used by yad-checks). Never auto-advances.",,{repo: <one of an epic's repos | hub>} {action: wire|route} {body: PR description file},3-build,yad-checks,,false,demo-repos/<repo>/,.github/pull_request_template.md .gitlab/merge_request_templates/Default.md checks/risk-route.sh checks/pr-title.sh checks/pr-template.sh
 SDLC Workflow,yad-commit,Commit by Convention,CM,"Build helper: commit ONE staged atomic change by the conventions — a Conventional-Commits subject, the fixed trailer block (Task -> Contract-Change -> Co-Authored-By), and the <=3-file atomic guard. The human git author owns the commit; an assisting AI is recorded only as a Co-Authored-By footer chosen per-commit with --ai (claude|copilot|cursor|coderabbit|none, default none). Drives the yad commit CLI. Never auto-advances.",,{type: feat|fix|...} {message: subject} {ai: <tool|none>} {task: <id>} {contract-change: true|false},3-build,yad-implement,,false,<repo>/,one commit
-SDLC Workflow,yad-open-pr,Open PR/MR,OP,"Build helper: open a code-repo task PR/MR from the committed platform template — detect GitHub/GitLab, push the task branch, create the PR/MR with the body prefilled (Summary / Story-task / Impact & Risk) and the title defaulting to the commit subject. Auto-assigns from the hub roster (assignee = committer, reviewers = repo reviewers + domain-owners); high risk / contract surface routes to domain owners (risk-route.sh). Bases the PR on the repo's RESOLVED default branch (repos.json default_branch, else the platform's own default, else origin/HEAD, else main) instead of a hardcoded main, and warns when the base is not the platform default — that loses the AI first pass irreversibly. Drives the yad open-pr CLI. Never merges; never auto-advances.",,{repo: <name>} {risk: low|medium|high} {contract-change: true|false} {base: <branch>},3-build,yad-commit,,false,<repo>/,one PR/MR
-SDLC Workflow,yad-ship,Commit + Open PR/MR,SP2,"Build helper: commit AND open the task PR/MR in one step — a thin orchestration over yad-commit then yad-open-pr. Commits the staged atomic change by the conventions, then pushes the branch and opens the PR/MR from the committed template with the roster auto-assigned. The PR step runs ONLY if the commit lands (a failed commit, tripped guard, or --dry-run stops before pushing). Drives the yad ship CLI. Never merges; never auto-advances.",,{type: feat|fix|...} {message: subject} {ai: <tool|none>} {repo: <name>} {risk: low|medium|high} {contract-change: true|false} {base: <branch>},3-build,yad-pr-template,,false,<repo>/,one commit + one PR/MR
-SDLC Workflow,yad-hub-bridge,Hub Review Bridge,HB,"The templated PR/MR bridge for the Shape review gate: when the product hub has a platform (.sdlc/hub.json), open a review PR/MR on the hub for an authored artifact, set required reviewers/labels from the routing rule, and provide the read-only gh/glab recipes yad-review-gate's sync uses to pull platform comments + approvals into the file ledger. Local-user auth, no stored tokens; file ledger stays the source of truth; degrades to local when no platform/CLI. Never auto-advances.",,{epic: EP-<slug>} {artifact: epic.md|architecture.md|ui-design.md|stories/} {action: open|route},1-front,yad-review-gate,yad-review-gate,false,epics/EP-<slug>/.sdlc/,hub-prs.json
-SDLC Workflow,yad-engineer-review,Engineer Review & Merge,ER,"Build Step E: wire an advisory AI first-pass (CodeRabbit) on the PR, record the human engineer review with the same human_approve discipline as the Shape gates (owner + 1 reviewer, escalating to domain owners on high risk / contract / auth / payments), and on merge record the ship in epics/<epic>/.sdlc/build-log.json and update the story state. AI review is advisory, never the authority; the human owns the merge. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {task: T0N} {repo: <repo>} {action: ai-review|approve|ship},3-build,yad-ship,,false,epics/EP-<slug>/.sdlc/,build-log.json story-status
+SDLC Workflow,yad-open-pr,Open PR/MR,OP,"Build helper: open a code-repo task PR/MR from the committed platform template — detect GitHub/GitLab, push the task branch, create the PR/MR with the body prefilled (Summary / Story-task / Impact & Risk) and the title defaulting to the commit subject. Assigns the logged-in gh/glab login and requests no reviewers; high risk / contract surface raises the approver count (risk-route.sh prints it). Bases the PR on the repo's RESOLVED default branch (--base, else repos.json default_branch, else hub.json default_branch for a PR on the Product itself, else the platform's own default, else origin/HEAD, else main) instead of a hardcoded main, and warns when the base is not the platform default — that loses the AI first pass irreversibly. Drives the yad open-pr CLI. Never merges; never auto-advances.",,{repo: <name>} {risk: low|medium|high} {contract-change: true|false} {base: <branch>},3-build,yad-commit,,false,<repo>/,one PR/MR
+SDLC Workflow,yad-ship,Commit + Open PR/MR,SP2,"Build helper: commit AND open the task PR/MR in one step — a thin orchestration over yad-commit then yad-open-pr. Commits the staged atomic change by the conventions, then pushes the branch and opens the PR/MR from the committed template, assigned to the logged-in gh/glab login with no reviewers requested. The PR step runs ONLY if the commit lands (a failed commit, tripped guard, or --dry-run stops before pushing). Drives the yad ship CLI. Never merges; never auto-advances.",,{type: feat|fix|...} {message: subject} {ai: <tool|none>} {repo: <name>} {risk: low|medium|high} {contract-change: true|false} {base: <branch>},3-build,yad-pr-template,,false,<repo>/,one commit + one PR/MR
+SDLC Workflow,yad-hub-bridge,Hub Review Bridge,HB,"The templated PR/MR bridge for the Shape review gate: when the Product has a platform (.sdlc/hub.json), open a review PR/MR on the Product for an authored artifact, apply the touched-domain labels (no reviewers are requested), and provide the read-only gh/glab recipes yad-review-gate's sync uses to pull platform comments + approvals into the file ledger. Local-user auth, no stored tokens; file ledger stays the source of truth; degrades to local when no platform/CLI. Never auto-advances.",,{epic: EP-<slug>} {artifact: epic.md|architecture.md|ui-design.md|stories/} {action: open|route},1-front,yad-review-gate,yad-review-gate,false,epics/EP-<slug>/.sdlc/,hub-prs.json
+SDLC Workflow,yad-engineer-review,Engineer Review & Merge,ER,"Build Step E: wire an advisory AI first-pass (CodeRabbit) on the PR, record the human engineer review with the same advance-human discipline as the Shape gates (1 approval from someone other than the author; high risk / contract / auth / payments add an advisory risk step), and on merge record the ship in epics/<epic>/.sdlc/build-log.json and update the story state. AI review is advisory, never the authority; the human owns the merge. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {task: T0N} {repo: <repo>} {action: ai-review|approve|ship},3-build,yad-ship,,false,epics/EP-<slug>/.sdlc/,build-log.json story-status
 SDLC Workflow,yad-backfill,Backfill Specs,BF,"Build Step G: generate specs for already-built features in an existing repo. Confirm Repomix (npx repomix CLI), pack ONE feature (compress + git logs, secret-scan), feed to AI with a 'describe what exists, do not invent' prompt, write a DRAFT spec marked verified: false. Human approval (reuse yad-review-gate) makes it real. Boundary auto-proposed and human-confirmed. A change is blocked only until the features it touches have approved specs. The promote action flips a brownfield stub epic (yad-stub) to a real, verified feature epic once its backfill spec is approved. Never auto-advances.",,{repo: <repo>} {feature: <name + globs>} {action: pack|draft|approve|gate|promote} {epic: EP-<slug> (promote)},3-build,,,false,demo-repos/<repo>/specs/backfill/<feature>/,spec.md backfill-check.sh
-SDLC Workflow,yad-run,Run (Automation),RN,"Phase 4 orchestrator: drive a story's Build loop (spec→tasks→implement→checks) in one code repo, reading each step's automation dial from build-state — on machine_advance it advances on its own, on human_approve it stops for a human. Records every run in the trust log. Realizes Step B (a clean checks pass auto-advances to the engineer review when earned; any FAIL / scope overrun / contract touch HALTS). set-dial earns/reverts a step's automation (machine_advance gated by the trust threshold; Shape steps and engineer-review refused); kill/unkill toggles the system-wide kill switch. Shape steps and the human merge gate never auto-advance.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <repo>} {action: run|set-dial|kill|unkill} {step: <back-step>} {to: human_approve|machine_advance},4-automate,yad-spec,yad-engineer-review,false,epics/EP-<slug>/.sdlc/,build-state/<story-id>.json trust-log.json
-SDLC Workflow,yad-status,SDLC Status,SS,"Read-only: print the full Shape step chain, per-step dials, contract lock, story repo tags, and pending approvals at the active gate. For stories in Build, also print each Build step's automation dial and status, the trust record (runs / % approved-unchanged / earned vs gathering evidence), and the system-wide kill-switch state.",,{epic: EP-<slug>},1-front,,,false,,
-SDLC Workflow,yad-report,Report Issue,RP,"Self issue reporter: when a yad flow breaks, file a well-formed bug in the upstream yadflow repo with AUTO-SCRUBBED diagnostics (yadflow/node/os version, tool present+authenticated booleans, hub platform enum, the YadError code/hint, a path-scrubbed message, and the failing command + flag NAMES only) — never absolute paths, hostnames, git URLs, repo names, roster logins/emails, epic/story IDs, branch names, or flag values. Searches open issues first to avoid duplicates, previews the exact payload, and asks before posting to the public repo; files via an authenticated gh/glab or a prefilled issues/new URL fallback. Also offered automatically after an unexpected failure (interactive only; YAD_NO_REPORT=1 disables). Never a gate, never touches epic state.",,{message: one-line summary},,,,false,,
+SDLC Workflow,yad-run,Run (Automation),RN,"Phase 4 orchestrator: drive a story's Build loop (spec→tasks→implement→checks) in one code repo, reading each step's advance dial through the engine (yad dial --json) — on auto it advances on its own, on human it stops for a human. Records every run in the trust log, the run record yad dial shows as advice. A clean checks pass on auto advances to the engineer review; any FAIL / scope overrun / contract touch HALTS. set-dial runs yad dial (no trust threshold since E34; a gate is refused); kill/unkill run yad kill / yad unkill, recorded in .sdlc/automation.json. Never drives a Shape step; the human merge gate never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <repo>} {action: run|set-dial|kill|unkill} {step: <back-step>} {to: human|auto},4-automate,yad-spec,yad-engineer-review,false,epics/EP-<slug>/.sdlc/,build-state/<story-id>.json trust-log.json
+SDLC Workflow,yad-status,SDLC Status,SS,"Read-only: print the full Shape step chain, per-step dials, contract lock, story repo tags, and pending approvals at the active gate. For stories in Build, also print each Build step's automation dial and status, the run record (runs / % approved-unchanged, as advice), the Shape author dials and the kill switch from .sdlc/automation.json.",,{epic: EP-<slug>},anytime,,,false,,
+SDLC Workflow,yad-report,Report Issue,RP,"Self issue reporter: when a yad flow breaks, file a well-formed bug in the upstream yadflow repo with AUTO-SCRUBBED diagnostics (yadflow/node/os version, tool present+authenticated booleans, Product platform enum, the YadError code/hint, a path-scrubbed message, and the failing command + flag NAMES only) — never absolute paths, hostnames, git URLs, repo names, logins/emails, epic/story IDs, branch names, or flag values. Searches open issues first to avoid duplicates, previews the exact payload, and asks before posting to the public repo; files via an authenticated gh (the upstream repo is on GitHub) or a prefilled issues/new URL fallback. Also offered automatically after an unexpected failure (interactive only; YAD_NO_REPORT=1 disables). Never a gate, never touches epic state.",,{message: one-line summary},,,,false,,
 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/hub.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: hub|<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},,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},,,,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 + 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>},,,,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/parent/thread/inherits/supersedes + a state.json whose inherited steps are pre-marked done and only the changed steps run; 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} {kind: change|defect|hotfix} {origin: production|staging|qa|review} {severity: sev1..sev4} {description: text} {affected: artifacts},1-front,,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},,,,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 kind:defect 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},,,,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>},,,,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 hub, 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 (kind: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},1-front,,yad-change,false,epics/EP-<slug>/,epic.md state.json approvals.json comments.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-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-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