yadflow 3.18.0 → 3.19.0-next.2

package/cli/update-commit.mjs

@@ -2,7 +2,7 @@
 // trees, commit the applied changes PER REPO (the hub and every connected repo) and push them
 // straight to the default branch, so a package update "just lands" everywhere instead of leaving
 // dirty trees for someone to hand-commit across N repos. This is the update-flow analogue of the
-// back-half `yad checkpoint` (cli/checkpoint.mjs) and reuses its machine-commit machinery.
+// Build `yad checkpoint` (cli/checkpoint.mjs) and reuses its machine-commit machinery.
 //
 // Invariants (shared with checkpoint):
 //   1. Stage an EXPLICIT per-repo allowlist — exactly the paths the reconcile actions declared they

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.18.0",
+  "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.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/sdlc/config.yaml

@@ -13,7 +13,7 @@ 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 half).
+# 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.
 discovery:
@@ -33,15 +33,15 @@ output_folder: "{project-root}/_bmad-output"
 defaults:
   assistance: review          # none | review | heavy
   automation: human_approve   # human_approve | machine_advance
-  # Front steps (discovery [optional front-zero], analysis [optional], epic, architecture,
+  # Shape steps (discovery [optional front-zero], 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
   # version (build plan §1, §8.7).
-  front_steps_locked: true
-  # Each front authoring step opens its own branch at the start of the step (the <step> is the step id:
+  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 bridge's review branch (hub.artifact_branch). See yad-epic/references/state-schema.md.
-  front_authoring_branch: "<step>/EP-<slug>"
+  # from the verified ledger's review branch (hub.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:
@@ -58,8 +58,8 @@ review_gate:
   # PR-driven automation (the `yad gate` CLI). With a hub 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,
-  # and (c) the review PR/MR is merged. The merge is the human approval act, so front steps still never
-  # machine_advance. The file ledger stays the source of truth; no platform / no gh|glab => file-only.
+  # 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_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.
@@ -85,11 +85,11 @@ review_gate:
     never_blocks: true          # invariant: a pair session is advisory; the gate predicate is untouched
     rubric: review-rubric.md    # the transferable review method (skills/yad-pair-review/references/)
 
-# Build half (Phase 3). Code repos are SEPARATE git repos (one .git each), not subfolders
+# Build (Phase 3). Code repos are SEPARATE git repos (one .git each), not subfolders
 # of the product repo — faithful to "per-repo specs in each code repo, contract singular in the
 # product repo" (phase-3-build-plan.md, Cross-cutting). Documentation-as-config for yad-spec (Step A).
 build:
-  code_repos_root: "{project-root}/demo-repos"   # throwaway demo code repos for this build half
+  code_repos_root: "{project-root}/demo-repos"   # throwaway demo code repos for this Build
   feature_id: story_id          # specs/<story-id>/ — pinned to the permanent story ID, not Spec Kit's auto-slug
   spec_layout: speckit          # follow Spec Kit's native spec/plan/tasks layout
   speckit_ceremony: [specify, clarify, plan, analyze, checklist, tasks]   # heavy run, once per story per repo
@@ -119,7 +119,7 @@ build:
   # Step C (yad-checks) — the CI gates that must pass before merge. CI-agnostic bash in checks/.
   # Phase 6 adds three thread-aware gates: lineage-check (every change links a real threaded epic),
   # epic-open (a SEALED epic — all stories shipped — refuses new behaviour, forcing a change-epic so the
-  # front artifacts can never go stale), and reconcile-debt (a hotfix's ship-first debt blocks the next
+  # 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
@@ -133,13 +133,13 @@ build:
   pr_templates:
     github: ".github/pull_request_template.md"
     gitlab: ".gitlab/merge_request_templates/Default.md"
-    hub:                                # front-half artifact-review PR/MR on the product hub (yad-pr-template repo:hub)
+    hub:                                # Shape artifact-review PR/MR on the product hub (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)
   # 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 (back-half analogue of approvals.json), stored shard-then-fold: writers add one
+  # Append-only ship ledger (Build analogue of approvals.json), stored shard-then-fold: writers add one
   # shard per ship under build_log_dir; `yad tidy up` folds a SHIPPED story's shards into build_log.
   # READERS MUST UNION the two (dedupe by (story, task, repo); a shard wins) — build_log alone omits every
   # unfolded ship, e.g. a `yad checkpoint --retro-ship` backfill or any ship on an `in-build` story.
@@ -157,16 +157,16 @@ build:
 # 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
 # each is cached so epic/architecture/ui/stories consider what already exists in the code. The product
-# repo is the FRONT-PHASE TOOLCHAIN HUB: repomix (and Impeccable) are installed/run here and target the
-# connected code repos by path — code repos need no install for this. (The build-half CI gates are the
+# repo is the Shape phase TOOLCHAIN HUB: 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]                        # front-phase toolchain, installed in the product hub
+  tools: [repomix, impeccable]                        # Shape phase toolchain, installed in the product hub
   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: front-phase
+  refresh: human                                      # a stale repo is a HUMAN decision: Shape phase
                                                       # skills FLAG it and stop (pointing at
                                                       # `yad repo refresh <repo>`) — they never silently
                                                       # re-pack. `yad repo list` shows fresh/stale;
@@ -174,7 +174,7 @@ code_context:
   # `yad repo sync [<repo>]` (yad-sync-repos) switches every connected repo to its default_branch and
   # fast-forwards it from origin before work starts — working-tree only (never writes the registry);
   # a dirty repo is skipped, a diverged branch is left for manual resolution (fast-forward only).
-  load_in_front_phases: true                          # epic, architecture, ui-design, stories read the maps
+  load_in_shape_phases: true                          # epic, architecture, ui-design, stories read the maps
   # Auth: `yad-connect-repos` clones/fetches as the LOCAL user (SSH key or git credential helper),
   # works for both github and gitlab (and self-hosted), and stores NO tokens in the registry.
   platforms: [github, gitlab]
@@ -251,16 +251,16 @@ docs:
   # tokens — publishing runs as the LOCAL user's own gh/glab or the platform CI. Idempotent, refreshable.
   auth: user
 
-# Hub platform + front-half 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 the bridge enabled, the front-half review/
+# 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
 # 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 file-only gate when there is no platform / no CLI.
+# 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)
-  bridge: true                                         # master enable; false => file-only front gates everywhere
+  bridge: true                                         # master enable; false => local Shape gates everywhere
   platforms: [github, gitlab]                          # detected from the hub'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
@@ -268,20 +268,20 @@ hub:
 
 # 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"). Front states are
+# 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.
 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 back step starts manual; machine_advance must be earned
-  # A back step is a CANDIDATE for machine_advance only once its trust-log slice clears this bar.
+  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 front authoring steps (already locked:true in state.json; analysis is optional) + the human
+  # 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
@@ -291,7 +291,7 @@ automation:
 # 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
 # change request becomes a NEW epic, threaded to its parent: a feature is a thread of linked epics
-# (genesis -> change -> defect -> ...). A change-epic INHERITS unchanged front artifacts from its parent
+# (genesis -> change -> defect -> ...). A change-epic INHERITS unchanged Shape artifacts from its parent
 # BY REFERENCE and only RE-AUTHORS what it changes — so artifacts are never stale, only superseded; the
 # feature's current truth is the head of the thread, and the chain IS the evolution timeline. See
 # docs/phase-6-build-plan.md and skills/yad-change. yad-defects/yad-timeline render it; yad-reconcile
@@ -299,7 +299,7 @@ automation:
 change:
   # The kind of an epic (epic.md frontmatter `kind:`). `feature` is the genesis (default when absent).
   kinds: [feature, change, defect, hotfix]
-  # Triage DEPTH (yad-change auto-proposes, human confirms) -> which front states are re-authored vs
+  # 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).
   depths: [defect-fix, behavioral-no-surface, contract-surface, new-capability]
@@ -321,7 +321,7 @@ change:
   # `architecture` from `inherits` is what triggers a real re-lock + the architecture gate.
   inherit_by: reference
   # An epic is SEALED once every story is `shipped` (build.story_build_states). epic-open.sh refuses new
-  # behaviour on a sealed epic -> the change must land in a new threaded change-epic (the front half is
+  # behaviour on a sealed epic -> the change must land in a new threaded change-epic (Shape is
   # forced to stay current; staleness is unshippable).
   seal_on: all-stories-shipped
   # Brownfield stub anchor (yad-stub): an already-built feature with NO epic can't be a change parent
@@ -337,6 +337,6 @@ change:
     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:
-    ship_first: true                    # a hotfix may run the build half BEFORE its front gates approve
+    ship_first: true                    # a hotfix may run Build BEFORE its Shape gates approve
     debt_blocks_next_change: true       # but opens reconcile-debt.json; the next change on the thread is blocked until paid
     debt_requires: [artifacts-updated, regression-test]   # evidence that clears the debt

package/skills/sdlc/module-help.csv

@@ -1,32 +1,32 @@
 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-analysis,Author Analysis,AN,"Optional front state: 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,"Front state 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-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-companion,Review Companion,RC,"Fun, easy, transparent review companion for the review gates (front gate AND back-half 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 (front gate AND back-half 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,"Front state 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,"Front state 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,"Front state 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,"Front state 9 (PARALLEL, non-blocking): opens when the stories gate passes — the epic is already ready-for-build, so the build half 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 front/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-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-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-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-spec,Author Spec,SP,"Build-half 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-half 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-half 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-half 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-commit,Commit by Convention,CM,"Build-half 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-half 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-half 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 front-half 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 file-only 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-half 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 front 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-backfill,Backfill Specs,BF,"Build-half 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 back-half 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; front states and engineer-review refused); kill/unkill toggles the system-wide kill switch. Front states 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 front-state chain, per-step dials, contract lock, story repo tags, and pending approvals at the active gate. For stories in the build half, also print each back-half 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-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-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-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-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

package/skills/yad-analysis/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: yad-analysis
-description: 'Optional front state 1 of the gated SDLC. 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 12-step chain that puts analysis before epic). Never auto-advances — hands off to the team review gate. Optional: if skipped, the epic step does this shaping inline. Use when the user says "analyse the idea", "start with analysis", or "author the analysis".'
+description: 'Optional Shape step 1 of the gated SDLC. 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 12-step chain that puts analysis before epic). Never auto-advances — hands off to the team review gate. Optional: if skipped, the epic step does this shaping inline. Use when the user says "analyse the idea", "start with analysis", or "author the analysis".'
 ---
 
-# SDLC — Author Analysis (optional front state 1)
+# SDLC — Author Analysis (optional Shape step 1)
 
 **Goal:** Produce a human-authored, AI-assisted `analysis.md` — the analyst's discovery brief that
 shapes the feature **before** the epic — assign its stable `EP-<slug>` ID, and initialise the per-epic
-state machine in `.sdlc/`. This is a **front state**: human-authored with AI assist and **never
+state machine in `.sdlc/`. This is a **Shape step**: human-authored with AI assist and **never
 auto-advances**. When the analysis is drafted, control passes to `yad-review-gate`.
 
 This step is **optional**. When it runs, it is the entry point: it assigns the ID and seeds the
@@ -15,7 +15,7 @@ This step is **optional**. When it runs, it is the entry point: it assigns the I
 analyst shaping inline and seeds the **10-step** chain — no behaviour change for teams that skip it.
 
 This skill enforces the build plan's core rules: all state lives in files; IDs are generated by the
-engine (never typed by hand); front steps are locked to `human_approve`.
+engine (never typed by hand); Shape steps are locked to `human_approve`.
 
 ## Conventions
 
@@ -71,7 +71,7 @@ never renamed** — renaming breaks every downstream link (build plan §6b). Che
 Open the analysis authoring branch `analysis/EP-<slug>` per the shared procedure
 (`references/state-schema.md` → "Authoring branches"): git-safe (skip with a note if `{project-root}`
 is not a git work tree), check out the branch if it exists, else create it from the hub's default
-branch. Author and commit `analysis.md` on it. This is **distinct** from the bridge's `review/…` branch.
+branch. Author and commit `analysis.md` on it. This is **distinct** from the verified ledger's `review/…` branch.
 
 ### Step 5 — Write the analysis (assist: analyst)
 Write `{project-root}/epics/EP-<slug>/analysis.md` using EXACTLY this template:
@@ -102,7 +102,7 @@ code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # which code-maps in
 Fill the body with the user; leave `owner` for the user to set.
 
 ### Step 6 — Seed the state machine
-Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **12-step** front-state
+Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **12-step** Shape step
 sequence (analysis before epic), all steps defaulting to `automation: human_approve`, with every
 authoring step **locked**. Use this exact shape (see `references/state-schema.md`):
 
@@ -134,24 +134,24 @@ Notes:
 - `architecture-review` carries `risk_tags: ["contract"]` so the gate escalates it by default
   (build plan §4): the contract review needs domain owners, not just owner + 1.
 - `test-cases` / `test-cases-review` are a **parallel, non-blocking track**: they seed `blocked` and open
-  when `stories-review` passes — the epic is already `ready-for-build` by then, so the build half runs
+  when `stories-review` passes — the epic is already `ready-for-build` by then, so Build runs
   alongside the tester (see `../yad-epic/references/state-schema.md`).
 - Also create an empty approvals ledger `{project-root}/epics/EP-<slug>/.sdlc/approvals.json`
   and an empty comments ledger `{project-root}/epics/EP-<slug>/.sdlc/comments.json`, each containing
   `[]`, and the `reviews/` directory.
 - Commit the seed on the `analysis/EP-<slug>` branch, and cut `review/EP-<slug>/analysis` from it so the
-  epic's **first** review PR/MR carries the ledger to the default branch. In bridge mode `ledger-guard`
+  epic's **first** review PR/MR carries the ledger to the default branch. In verified mode `ledger-guard`
   exempts a new epic's ledger (creation, not mutation, #162); every later change to it is CI's. See
   `../yad-epic/references/state-schema.md`, "Authoring branches".
 
 ### Step 7 — Stop at the gate (do NOT advance)
 Report: epic ID, the path to `analysis.md`, and that the next action is **review** via
 `yad-review-gate` (base rule: owner + 1 reviewer). **Never mark the analysis-review step approved
-here** — only real reviewers do that through the gate. Front states do not auto-advance. When the
+here** — only real reviewers do that through the gate. Shape steps do not auto-advance. When the
 analysis gate passes, control moves to `yad-epic`, which reads `analysis.md` as input. When the
 hub has a platform, the gate opens a review PR on the hub (via `yad-hub-bridge`) and
 `yad-review-gate action: sync` pulls platform approvals/comments into the ledger; otherwise the review
-is recorded file-only.
+is recorded local.
 
 ## Reference
 - State schema, the two chain shapes, and the authoring-branch procedure:

package/skills/yad-architecture/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: yad-architecture
-description: 'Front state 3 of the gated SDLC. With the architect, author architecture.md and the locked contract.md (the shared cross-repo surface), then hash-lock the contract surface into .sdlc/contract-lock.json. Reads epic.md as input. Never auto-advances — hands off to the team review gate (which escalates on the contract risk tag). Use when the user says "author the architecture" or after the epic gate passes.'
+description: 'Shape step 3 of the gated SDLC. With the architect, author architecture.md and the locked contract.md (the shared cross-repo surface), then hash-lock the contract surface into .sdlc/contract-lock.json. Reads epic.md as input. Never auto-advances — hands off to the team review gate (which escalates on the contract risk tag). Use when the user says "author the architecture" or after the epic gate passes.'
 ---
 
-# SDLC — Author Architecture + Contract (front state 3)
+# SDLC — Author Architecture + Contract (Shape step 3)
 
 **Goal:** Produce a human-authored, AI-assisted `architecture.md` and the **locked** `contract.md`
 for an approved epic, then record a hash-lock of the contract surface so a later contract-check can
-detect drift. This is a **front state**: human-authored with AI assist, **never auto-advances**.
+detect drift. This is a **Shape step**: human-authored with AI assist, **never auto-advances**.
 When both artifacts are drafted, control passes to `yad-review-gate`, which **escalates** this review
 by default (the architecture step carries `risk_tags: ["contract"]`).
 
 This skill enforces the build plan's core rules: all state lives in files; the contract holds only the
-shared cross-repo surface at charter altitude; front steps stay locked to `human_approve`.
+shared cross-repo surface at charter altitude; Shape steps stay locked to `human_approve`.
 
 ## Conventions
 
@@ -37,7 +37,7 @@ Open the architecture authoring branch `architecture/EP-<slug>` per the shared p
 (`../yad-epic/references/state-schema.md` → "Authoring branches"): git-safe (skip with a note
 if `{project-root}` is not a git work tree), check out the branch if it exists, else create it from the
 hub's default branch. Author and commit `architecture.md` / `contract.md` / `contract-lock.json` on it.
-This is **distinct** from the bridge's `review/…` branch.
+This is **distinct** from the verified ledger's `review/…` branch.
 
 ### Step 2 — Read the epic as input context
 Read `epic.md`. Note `repos` (the touched domains), the goal, scope, and acceptance signals. The
@@ -179,9 +179,9 @@ awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' \
 
 ### Step 6 — Advance the authoring step (NOT the gate)
 **Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
-**bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`.
+**verified mode** is `platform` set AND `ledger: "verified"` — or, on a project that has not run `yad migrate` yet, `bridge_enabled` (or legacy `bridge`) `true`. `ledger` wins whenever it is present.
 
-**Bridge mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
+**verified mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
 any non-bot commit touching `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or
 `epics/*/reviews/*.md`, `yad gate open` deliberately skips this write for the same reason, and
 `yad gate ci --merged` performs the whole transition when the review PR merges. Making the edit here
@@ -189,7 +189,7 @@ fails the gate if it rides the review PR, and desynchronises the ledger CI is ab
 is pushed around the gate. Commit the artifact set — **`architecture.md`, `contract.md`, and
 `.sdlc/contract-lock.json`** (artifact-side, not ledger) — then hand off to `yad-review-gate`.
 
-**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
+**Otherwise — local, or a platform with no gate-sync CI — write it.** In `state.json`: set
 `architecture.status: "done"`, set `architecture-review.status: "in_review"`, and set
 `currentStep: "architecture-review"`. Write `state.json`. Do **not** touch `approvals.json` — only
 real reviewers approve, through the gate. On this branch `yad gate open` makes the same edit, so it
@@ -199,10 +199,10 @@ is a no-op once the gate has run.
 Report: the paths to `architecture.md`, `contract.md`, and `contract-lock.json`; the contract hash;
 and that the next action is **review** via `yad-review-gate`. Note that this review **escalates**
 (risk tag `contract`): it needs owner + 1 reviewer **plus a domain owner for each touched repo**.
-**Never record approval here.** Front states do not auto-advance. When the hub has a platform, the gate
+**Never record approval here.** Shape steps do not auto-advance. When the hub has a platform, the gate
 opens a review PR on the hub (via `yad-hub-bridge`, labelled per touched repo) and
 `yad-review-gate action: sync` pulls platform approvals/comments into the ledger; a contract re-lock
-invalidates prior platform approvals too. Otherwise the review is recorded file-only.
+invalidates prior platform approvals too. Otherwise the review is recorded local.
 
 ## Reference
 - Contract surface, altitude rule, and hashing recipe: `references/contract-format.md`.

package/skills/yad-architecture/references/contract-format.md

@@ -1,6 +1,6 @@
 # Contract surface — format, altitude, and hash-lock
 
-The `contract.md` produced at front state 3 is the **single source of truth for the shared cross-repo
+The `contract.md` produced at Shape step 3 is the **single source of truth for the shared cross-repo
 surface** of an epic. Phase 3's contract-check (not built yet) fails a PR when a repo drifts from this
 surface. To make that check possible, the surface is delimited and hash-locked now.
 
@@ -70,6 +70,5 @@ awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' \
 
 ## Why a hash (vs structured diff)
 
-A hash is the smallest representation that proves "did the agreed surface change?" — which is all the
-front half needs. A field-by-field structured diff is a Phase 3 concern (it tells you *what* drifted in
+A hash is the smallest representation that proves "did the agreed surface change?" — which is all Shape needs. A field-by-field structured diff is a Phase 3 concern (it tells you *what* drifted in
 a failing PR); the lock established here is what that future check compares against.

package/skills/yad-backfill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-backfill
-description: 'Build-half Step G of the gated SDLC — backfill: generate specs for already-built features in an existing repo so new work does not break them. Confirm Repomix (the one true CLI subprocess: npx repomix), pack ONE feature at a time (compress + git logs, secret-scan), feed it to AI with a "describe what exists, do not invent" prompt, and write a DRAFT spec marked unverified. Require human approval (reuse yad-review-gate) before the spec counts as real. Boundary is auto-proposed from the project convention and human-confirmed. A change is blocked only until the features IT touches have approved specs. The `promote` action flips a brownfield stub epic (minted by yad-stub, so defects could thread off it) to a real, verified feature epic once its backfill spec is approved. Use when the user says "backfill specs", "document an existing feature", "spec the legacy code", or "promote the stub epic".'
+description: 'Build Step G of the gated SDLC — backfill: generate specs for already-built features in an existing repo so new work does not break them. Confirm Repomix (the one true CLI subprocess: npx repomix), pack ONE feature at a time (compress + git logs, secret-scan), feed it to AI with a "describe what exists, do not invent" prompt, and write a DRAFT spec marked unverified. Require human approval (reuse yad-review-gate) before the spec counts as real. Boundary is auto-proposed from the project convention and human-confirmed. A change is blocked only until the features IT touches have approved specs. The `promote` action flips a brownfield stub epic (minted by yad-stub, so defects could thread off it) to a real, verified feature epic once its backfill spec is approved. Use when the user says "backfill specs", "document an existing feature", "spec the legacy code", or "promote the stub epic".'
 ---
 
 # SDLC — Backfill (existing-code specs)
@@ -92,17 +92,17 @@ thread off it, `promote` is what makes that anchor real — run it once the feat
   - **`state.json`:** **remove** the top-level `kind: "stub"`, and move `currentStep` off the
     `backfill-pending` sentinel (per the promote flavour below).
 - **Light promote (default):** the feature's documentation lives in the approved backfill spec — do NOT
-  wake the front chain. Set `state.json` `currentStep: "backfill-done"` (a terminal sentinel, like
+  wake the Shape chain. Set `state.json` `currentStep: "backfill-done"` (a terminal sentinel, like
   `discovery-done`): the epic is now a real, verified anchor and its later evolution threads normally with
   `yad-change`. `yad next` then reports it as a documented anchor, not a pending stub.
-- **Full promote (opt-in):** to bring the feature fully under the front half and lock a real contract,
+- **Full promote (opt-in):** to bring the feature fully under Shape and lock a real contract,
   "wake" the state chain — set `currentStep: "epic"`, `epic` step `status: "in_progress"` — then run
   `yad-epic` → `yad-architecture` → … the normal way. This re-locks a contract that subsequent thread
   changes will inherit.
-- **Bridge mode — promote is not wired.** The `state.json` edits above mutate an epic whose ledger is
+- **verified mode — promote is not wired.** The `state.json` edits above mutate an epic whose ledger is
   already on the base ref, so the `#162` seed exemption does not apply and `ledger-guard` rejects the
   commit; unlike the authoring steps there is no `yad backfill` CLI and no `gate ci` path that performs
-  the promotion instead. On a bridge hub, STOP and report this — the promotion needs the gate bot (or a
+  the promotion instead. On a verified hub, STOP and report this — the promotion needs the gate bot (or a
   maintainer landing it out of band). Only the `epic.md` half is safe to commit. Tracked as a gap; do
   **not** push the ledger edit around the guard.
 - Never auto-advances; a human confirms the promotion.