yadflow 3.5.3 → 3.6.1

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [3.5.3](https://github.com/abdelrahmannasr/yadflow/compare/v3.5.2...v3.5.3) (2026-07-03)
+## [3.6.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.6.0...v3.6.1) (2026-07-04)
 
 
 ### Bug Fixes
 
-* fill the PR spec dir and summary from the task and commit ([a402a54](https://github.com/abdelrahmannasr/yadflow/commit/a402a545715eeea8aef2dde5426eb7f2538687a0))
+* **gate:** include the Checklist section in the hub review-PR body ([3134f89](https://github.com/abdelrahmannasr/yadflow/commit/3134f89658a172a3a346cf0945f62e6fa63bac74)), closes [#103](https://github.com/abdelrahmannasr/yadflow/issues/103)
 
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
 

package/README.md

@@ -72,7 +72,7 @@ In one pass it produces:
 
 - **The `yad` CLI** — zero-dependency Node (`setup`, `gate`, `commit`, `open-pr`, `ship`, `repo`,
   `thread`, `reconcile`, `usage`, `doctor`), run via `npx` or a global install.
-- **37 workflow skills** installed into your AI assistant — **Claude Code** (`.claude/`) first-class,
+- **38 workflow skills** installed into your AI assistant — **Claude Code** (`.claude/`) first-class,
   plus `.agents`, Zencoder, and OpenCode.
 - **`.sdlc/` config** — the product hub, connected repos, reviewer roster, and tool connections
   (design, testing, learning), all as plain JSON you can read and diff.
@@ -157,7 +157,7 @@ workflow-hygiene flags — derived read-only, so an EM can see how the team actu
 - **[Terminology & workflow report](https://abdelrahmannasr.github.io/yadflow/)** — every term, artifact, gate, and skill on one illustrated page.
 - **[TEAM-GUIDE.md](TEAM-GUIDE.md)** — the short, plain-language version for a developer team.
 - **[docs/CLI.md](docs/CLI.md)** — the full `yad` command reference, the PR-driven gate, and `yad doctor` codes.
-- **[docs/SKILLS.md](docs/SKILLS.md)** — the catalogue of all 37 agent skills.
+- **[docs/SKILLS.md](docs/SKILLS.md)** — the catalogue of all 38 agent skills.
 - **[docs/WALKTHROUGH.md](docs/WALKTHROUGH.md)** — the by-hand, end-to-end path through every phase.
 - **[CONTRIBUTING.md](CONTRIBUTING.md)** · **[RESEARCH-NOTES.md](RESEARCH-NOTES.md)** · **[RELEASING.md](RELEASING.md)**
 

package/cli/epic-state.mjs

@@ -396,6 +396,18 @@ export function buildNextActions(buildStates = []) {
   }));
 }
 
+// Classify a stub / backfill anchor from its ledger state — the SINGLE source of truth so `nextAction`
+// and `preconditionsMet` can never disagree, even on a partially-applied `promote`. The `stub` check
+// takes precedence over `backfill-done`, so a half-cleared promote (`kind:stub` still set while
+// `currentStep` already moved) reads as still-a-stub — the conservative side (needs promoting). Returns
+// `'stub'` (un-promoted anchor), `'documented'` (light-promoted anchor), or `null` (a normal epic).
+export function backfillAnchorKind(state) {
+  if (!state) return null;
+  if (state.kind === 'stub' || state.currentStep === 'backfill-pending') return 'stub';
+  if (state.currentStep === 'backfill-done') return 'documented';
+  return null;
+}
+
 // PURE precondition guard. Is `stepId` runnable right now? A step is runnable iff every step BEFORE it
 // in the chain is `done` and the step itself is not already `done`. With no state yet (greenfield), the
 // only runnable steps are the entry authoring steps (analysis | epic). Used by `yad next --check`
@@ -405,6 +417,18 @@ export function preconditionsMet(state, stepId) {
     const ok = stepId === 'epic' || stepId === 'analysis' || stepId === 'discovery';
     return { ok, blockedBy: null, reason: ok ? 'entry step (no state seeded yet)' : `start with yad-epic — no epic state for '${stepId}'` };
   }
+  // A stub anchor (backfill-pending) or a light-promoted anchor (backfill-done) has NO runnable front
+  // step: its front chain is intentionally left `blocked`. It evolves via `yad-backfill promote` / a
+  // threaded `yad-change`, never by authoring `epic` against the anchor itself — so the precondition
+  // guard must not green-light one (its blocked steps would otherwise read as "entry step ready").
+  const anchorKind = backfillAnchorKind(state);
+  if (anchorKind) {
+    const anchor = anchorKind === 'documented';
+    return { ok: false, blockedBy: null,
+      reason: anchor
+        ? `${stepId} is not runnable — this is a documented backfill anchor; evolve it with yad-change`
+        : `${stepId} is not runnable — this is a stub (backfill pending); run yad-backfill then promote, or thread a change with yad-change` };
+  }
   const i = state.steps.findIndex((s) => s.id === stepId);
   if (i === -1) return { ok: false, blockedBy: null, reason: `unknown step '${stepId}'` };
   if (state.steps[i].status === 'done') return { ok: false, blockedBy: null, reason: `${stepId} is already done` };
@@ -449,6 +473,26 @@ export function nextAction(ledger, { epic } = {}) {
       why: dpr ? `review PR #${dpr.number} is open — sync its state to advance` : `${dstep.id} is open — create the review PR/MR` };
   }
 
+  // A STUB genesis epic (yad-stub) or a light-promoted anchor: classified by the SHARED
+  // `backfillAnchorKind` helper (the same one `preconditionsMet` uses), so the two readers can never
+  // disagree — even on a partially-applied `promote`. A stub is (epic.md `stub:backfill-pending`) ⟺
+  // (state.kind:stub + currentStep:backfill-pending); `yad-backfill promote` clears ALL of these
+  // atomically (see state-schema.md), keeping this sentinel in step with `isStubEpic` (frontmatter).
+  const anchorKind = backfillAnchorKind(state);
+  if (anchorKind === 'stub') {
+    // No build half until backfilled + promoted — route to yad-backfill (not to authoring the epic),
+    // and remind that bugs can thread off it now with yad-change.
+    return { epicId, kind: 'backfill-pending', step: 'backfill-pending', status: 'stub',
+      why: 'stub epic (backfill pending) — document the code with yad-backfill then `yad-backfill promote` to make it real; thread bugs now with yad-change' };
+  }
+  if (anchorKind === 'documented') {
+    // `yad-backfill promote` documented the feature (verified) but did NOT wake the front chain (its docs
+    // live in the backfill spec). Terminal like `discovery-done` — no build half runs directly; the
+    // feature evolves by threading a change/defect off it.
+    return { epicId, kind: 'backfill-done', step: 'backfill-done', status: 'documented',
+      why: 'backfilled anchor (documented) — no build half runs directly; evolve it by threading a change/defect with yad-change' };
+  }
+
   // The parallel test-cases track stays workable even once the epic is ready-for-build.
   const tc = state.steps.find((s) => s.id === 'test-cases');
   const tcOpen = !!tc && tc.status !== 'done' && tc.status !== 'blocked';
@@ -527,6 +571,14 @@ export function epicLineage(root, epic) {
   };
 }
 
+// Is this a STUB genesis epic (minted by yad-stub as a brownfield thread anchor)? A stub is kind:feature
+// but carries `stub: backfill-pending` in epic.md frontmatter until `yad-backfill promote` flips it to a
+// real, verified epic (which clears the marker). Missing/greenfield-safe. Read by yad thread / yad-status
+// / the reconciler to render "stub (backfill pending)" and never treat it as a fully-specced feature.
+export function isStubEpic(root, epic) {
+  return readFrontmatter(path.join(epicRoot(root, epic), 'epic.md')).stub === 'backfill-pending';
+}
+
 // Walk `parent` to the thread root. Cycle- and missing-safe. Returns the genesis-first `chain`, the
 // computed `rootId`, and a `broken` reason (missing parent dir, a cycle, or a denormalized `thread`
 // cache that disagrees with the computed root) — the signal yad doctor / yad next --check report.

package/cli/gate.mjs

@@ -645,7 +645,7 @@ export async function gateTrailer(root, { epic, artifact, body, number, getBody
 // ---- helpers ------------------------------------------------------------------------------------
 const base = (artifact) => artifactBase(artifact);
 
-function fillHubTemplate({ epic, artifact, step, owner, domains }) {
+export function fillHubTemplate({ epic, artifact, step, owner, domains }) {
   return [
     '## Artifact under review',
     `- Epic: \`${epic}\``,
@@ -660,6 +660,15 @@ function fillHubTemplate({ epic, artifact, step, owner, domains }) {
     '## How to review (this drives the gate)',
     '- **Approve** to record your approval; **comment / request changes** to hold the gate.',
     '- This step advances when approvals are satisfied, all threads are resolved, and this PR is merged.',
+    '',
+    // Required by the hub `pr-template` gate (check_hub_body). Mirrors the Checklist block of the
+    // committed static template (yad-pr-template/templates/hub/<platform>/) so the generated body
+    // passes on the first CI run.
+    '## Checklist',
+    '- [ ] `owner` set in the artifact frontmatter (inherited from `epic.md`)',
+    '- [ ] Contract re-locked (`.sdlc/contract-lock.json`) if the surface changed (architecture only)',
+    '- [ ] Risk tags reflect the real surface touched (contract/auth/payments escalate)',
+    '- [ ] No secrets or tokens in the artifact or this description',
   ].join('\n');
 }
 

package/cli/manifest.mjs

@@ -56,6 +56,7 @@ export const SKILLS = [
   'yad-timeline',
   'yad-defects',
   'yad-reconcile',
+  'yad-stub',
 ];
 
 // Pre-2.0 skill names (the sdlc-* -> yad-* rename). `check`/`update` migrate any install

package/cli/next.mjs

@@ -1,6 +1,6 @@
 // `yad next` — the unified next-step driver. Read-only: it never writes state or acts. It reads the
 // file ledger and prints the ONE concrete, copy-pasteable next action (and a one-line why), so a user
-// never has to remember which of the 37 skills / gate commands comes next. "Guide, don't act" — the
+// never has to remember which of the 38 skills / gate commands comes next. "Guide, don't act" — the
 // front half still never auto-advances. Once an epic is `ready-for-build`, it reads each story's
 // build-state and prints the next BUILD sub-step per repo (spec → tasks → implement → checks → engineer-review)
 // plus the remaining chain — so the build half is guided too, not just hinted at.
@@ -91,6 +91,10 @@ function actionLine(a, { solo } = {}) {
     }
     case 'discovery-done':
       return `invoke the ${c.bold('yad-epic')} skill ${c.dim('(seed a feature epic from roadmap.md)')}`;
+    case 'backfill-pending':
+      return `invoke the ${c.bold('yad-backfill')} skill ${c.dim('(document the code, then `yad-backfill promote` — or thread bugs now with yad-change)')}`;
+    case 'backfill-done':
+      return `invoke the ${c.bold('yad-change')} skill ${c.dim('(documented anchor — evolve it by threading a change/defect off it)')}`;
     default:
       return c.dim('nothing to do');
   }

package/cli/thread.mjs

@@ -6,7 +6,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { c, log, ok, info, warn, hand, readJSON, exists } from './lib.mjs';
 import {
-  epicRoot, isValidEpicId, epicLineage, readFrontmatter,
+  epicRoot, isValidEpicId, epicLineage, readFrontmatter, isStubEpic,
   resolveThread, threadEpics, resolveCurrentArtifacts, resolveCurrentStories, THREAD_ARTIFACT_BASES,
 } from './epic-state.mjs';
 
@@ -54,6 +54,7 @@ export function threadSummary(root, threadOrEpic) {
       id, kind: lin.kind, parent: lin.parent, inherits: lin.inherits,
       currentStep: state?.currentStep || 'unseeded',
       sealed: sealedEpic(root, id),
+      stub: isStubEpic(root, id),
       depth: change?.depth || null,
       defect: change?.defect || null,
       brokenThread: resolveThread(root, id).broken || null,
@@ -86,7 +87,8 @@ export async function runThread(root, { epic, json = false } = {}) {
     for (const r of [...roots].sort()) {
       const s = threadSummary(root, r);
       const debt = s.openDebt.length ? c.red(`  ⚠ ${s.openDebt.length} open reconcile-debt`) : '';
-      log(`  ${c.bold(r)}  ${c.dim(`${s.nodes.length} epic(s)`)}${debt}`);
+      const stub = s.nodes[0]?.stub ? c.yellow('  [stub · backfill pending]') : '';
+      log(`  ${c.bold(r)}  ${c.dim(`${s.nodes.length} epic(s)`)}${stub}${debt}`);
     }
     log(c.dim('\n  yad thread <epic>   show one thread in full'));
     return;
@@ -100,8 +102,9 @@ export async function runThread(root, { epic, json = false } = {}) {
   for (const n of s.nodes) {
     const tag = KIND_TAG[n.kind] || n.kind;
     const seal = n.sealed ? c.dim(' [sealed]') : '';
+    const stub = n.stub ? c.yellow(' [stub · backfill pending]') : '';
     const dep = n.depth ? c.dim(` ${n.depth}`) : '';
-    log(`  • ${c.bold(n.id)}  ${tag}${dep}  ${c.dim('@ ' + n.currentStep)}${seal}`);
+    log(`  • ${c.bold(n.id)}  ${tag}${dep}  ${c.dim('@ ' + n.currentStep)}${seal}${stub}`);
     if (n.parent) log(c.dim(`      parent: ${n.parent}   inherits: [${n.inherits.join(', ') || '—'}]`));
     if (n.defect) log(c.dim(`      defect: ${n.defect.severity || '?'} · escaped@${n.defect.escape_stage || '?'} · ${n.defect.root_cause || ''}`));
     if (n.brokenThread) log(c.red(`      ✗ ${n.brokenThread}`));
@@ -161,6 +164,8 @@ export async function runReconcile(root, { action = 'check', thread = null } = {
     log('');
     info('refresh is advisory: open a reconcile change-epic with `yad-change` (kind: change) threaded to');
     info('the affected feature, then pay any open debt (update artifacts + add a regression test).');
+    info('for shipped brownfield code with NO epic at all, anchor it first with `yad-stub`, then thread');
+    info('the change/defect off that stub (and run `yad-backfill` to make the anchor real).');
   }
   if (action === 'wire') {
     log('');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yadflow",
-  "version": "3.5.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). A BMAD module + 37 yad-* skills.",
+  "version": "3.6.1",
+  "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",
   "license": "MIT",

package/skills/sdlc/config.yaml

@@ -146,6 +146,7 @@ build:
     pack_flags: "--compress --include <globs> --include-logs --style markdown"   # one feature at a time; Secretlint by default
     spec_location: "specs/backfill/<feature>/spec.md"   # draft (verified: false) until a human approves
     gate_scope: touched-features   # block a change only until the features it touches have approved specs
+    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
@@ -317,6 +318,18 @@ change:
   # behaviour on a sealed epic -> the change must land in a new threaded change-epic (the front half 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
+  # (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
+  # 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
+    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
     debt_blocks_next_change: true       # but opens reconcile-debt.json; the next change on the thread is blocked until paid

package/skills/sdlc/install.sh

@@ -11,7 +11,7 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 cd "$ROOT"
 
-SKILLS=(yad-discovery yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-test-cases yad-connect-repos yad-sync-repos yad-connect-design yad-connect-testing yad-connect-learning yad-connect-docs yad-docs yad-docs-overview yad-docs-sync yad-learn yad-spec yad-implement yad-checks yad-pr-template yad-hub-bridge yad-commit yad-open-pr yad-ship yad-engineer-review yad-backfill yad-run yad-review-gate yad-review-companion yad-pair-review yad-status yad-report yad-change yad-timeline yad-defects yad-reconcile)
+SKILLS=(yad-discovery yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-test-cases yad-connect-repos yad-sync-repos yad-connect-design yad-connect-testing yad-connect-learning yad-connect-docs yad-docs yad-docs-overview yad-docs-sync yad-learn yad-spec yad-implement yad-checks yad-pr-template yad-hub-bridge yad-commit yad-open-pr yad-ship yad-engineer-review yad-backfill yad-run yad-review-gate yad-review-companion yad-pair-review yad-status yad-report yad-change yad-timeline yad-defects yad-reconcile yad-stub)
 
 # Skills removed in a later release: this installer only refreshes names still in SKILLS, so a
 # rerun would otherwise leave a dropped skill sitting in the IDE dirs. Purge any lingering copy

package/skills/sdlc/module-help.csv

@@ -24,7 +24,7 @@ SDLC Workflow,yad-open-pr,Open PR/MR,OP,"Build-half helper: open a code-repo tas
 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},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. Never auto-advances.",,{repo: <repo>} {feature: <name + globs>} {action: pack|draft|approve|gate},3-build,,,false,demo-repos/<repo>/specs/backfill/<feature>/,spec.md backfill-check.sh
+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-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,,
@@ -35,4 +35,5 @@ SDLC Workflow,yad-docs-sync,Docs Sync,DY,"Maintenance/CI: keep the generated doc
 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 + build-log.json. 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 build-log.json, 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 scaffolds a reconcile change-epic stub (hands to yad-change) — 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-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

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. Use when the user says "backfill specs", "document an existing feature", or "spec the legacy code".'
+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".'
 ---
 
 # SDLC — Backfill (existing-code specs)
@@ -26,7 +26,9 @@ have approved specs — never the whole repo at once.
 
 - `repo` — the existing code repo to backfill.
 - `feature` — the feature name (and its file globs, e.g. `src/<feature>/**`).
-- `action` — `pack` | `draft` | `approve` | `gate` (default `pack`).
+- `action` — `pack` | `draft` | `approve` | `gate` | `promote` (default `pack`).
+- `epic` — `promote` only: the stub epic `EP-<slug>` (minted by `yad-stub`) to flip to real once the
+  feature's backfill spec is approved.
 
 ## On Activation
 
@@ -74,9 +76,33 @@ that feature's spec is `verified: true`. It is **per touched feature** — a cha
 not blocked by an unverified feature B. Forward-spec'd features (those with their own `specs/<story>/`)
 are not this gate's concern.
 
-### Step 6 — Stop (no auto-advance)
-Report the packed feature, the draft path (or the approval), and what is still unverified. Nothing
-auto-advances; a human owns the approval.
+### Step 6 — `promote` (flip a stub epic → real, once its spec is approved)
+When a brownfield feature was anchored with a **stub genesis epic** (`yad-stub`) so that defects could
+thread off it, `promote` is what makes that anchor real — run it once the feature's backfill spec is
+`verified: true`. Given `epic EP-<slug>` (a stub: `stub: backfill-pending` / `verified: false`):
+- **Verify readiness:** the matching `specs/backfill/<feature>/spec.md` must exist and be
+  `verified: true`. If not, STOP — approve the spec first (Step 4).
+- **Clear the stub markers ATOMICALLY.** A stub is marked in two files at once — `epic.md`
+  (`stub: backfill-pending`) **and** `state.json` (top-level `kind: "stub"` + `currentStep:
+  "backfill-pending"`). Promote must clear **all** of them together, or `yad next` (reads `state.json`)
+  and `yad thread` / `yad-status` (read `epic.md`) will disagree about whether the epic is still a stub.
+  - **`epic.md`:** set `verified: true`, **remove** the `stub:` marker, and add a `backfill:` block linking
+    the approved spec, e.g. `backfill: { spec: specs/backfill/<feature>/spec.md, promoted: <YYYY-MM-DD> }`.
+  - **`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
+  `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,
+  "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.
+- Never auto-advances; a human confirms the promotion.
+
+### Step 7 — Stop (no auto-advance)
+Report the packed feature, the draft path (or the approval / promotion), and what is still unverified.
+Nothing auto-advances; a human owns the approval.
 
 ## Hard rules (build plan §G, Cross-cutting)
 
@@ -88,4 +114,6 @@ auto-advances; a human owns the approval.
 ## Reference
 - The "describe what exists" prompt, the spec shape, and the gate: `references/backfill.md`.
 - The human approval discipline reused: `../yad-review-gate/SKILL.md`.
+- Minting the stub epic that `promote` later flips to real (brownfield thread anchor):
+  `../yad-stub/SKILL.md`.
 - Repomix flags: `RESEARCH-NOTES.md` §3.

package/skills/yad-change/SKILL.md

@@ -54,6 +54,13 @@ lineage is broken (a cycle, or a `thread` cache ≠ the computed root) — fix t
 parent is a **genesis epic not yet migrated** (no `kind:`), migrate it now: add `kind: feature` and
 `thread: <its own id>` to its `epic.md` (a one-line, non-gated frontmatter add).
 
+**Missing parent (brownfield) — never silent.** If the requested `parent` does **not exist at all**
+because the feature was built before it had an epic, do NOT dead-end: point the user at **`yad-stub`** to
+mint a stub genesis epic (a minimal `kind: feature` thread anchor) for that feature first, then re-run
+this skill with that stub as the `parent`. A change MUST still thread to a real parent — `yad-stub` just
+creates the smallest real one so the defect can be captured now (the `yad-reconcile` → anchor → change
+discipline).
+
 The new epic's `thread` = the parent's thread (the genesis id). Its `parent` = the given `parent` (the
 immediate predecessor — usually the current tip; if the parent is not the tip, see "concurrent changes"
 in `references/triage.md`).
@@ -132,11 +139,25 @@ When `architecture` is **inherited**, materialize the **pointer-lock** `.sdlc/co
 There is no `contract.md` in the change-epic, so the surface cannot drift, and `contract-check` passes
 unchanged because the hash is identical. (Exact recipe + field shapes: `references/triage.md`.)
 
+**Stub parent (brownfield, no locked surface yet).** When the `parent` is a **stub**
+(`stub: backfill-pending` / `verified: false`, minted by `yad-stub`), it has no `architecture.md` /
+`contract.md` / `ui-design.md` to inherit — the surface has not been documented yet. So for the bases the
+stub lacks, mark the inherited steps `"inherited": true, "inheritedFrom": "<stub>", "boundHash": null`
+(a `null` boundHash is treated as "nothing locked upstream → no drift" by the gate predicate, so the step
+passes and never blocks), and write **NO** `contract-lock.json` (there is no surface to point at — the
+child never touches `specs/*/contracts/**`, so `contract-check` passes trivially). Contract protection on
+this thread begins only after `yad-backfill promote` documents and locks the feature. Record
+`"parentStub": true` in `change.json` so it is auditable that the change threaded off an undocumented
+stub. Prefer the `defect-fix` / `behavioral-no-surface` depth against a stub — a `contract-surface`
+change against an undocumented feature should wait until the stub is promoted (backfilled + a real
+contract locked).
+
 ### Step 6 — Write `.sdlc/change.json` (intake + triage record)
 Record the intake: `epicId`, `thread`, `parent`, `kind`, `depth`, `intakeBy`, `intakeDate`, `title`,
 `description`, `affectedArtifacts`, `reauthors`, `inherits`, and for a defect/hotfix the `defect` block
 (`origin`, `severity`, `escape_stage`, `root_cause`). This is what `yad-defects` reads to attribute the
-defect to the gate that should have caught it.
+defect to the gate that should have caught it. Add `"parentStub": true` when the parent is an
+un-promoted stub (Step 5) — omit it (or `false`) otherwise.
 
 ### Step 7 — Hotfix only: record the ship-first exception + open reconcile debt
 If `kind: hotfix`, the build half MAY run before these front gates approve (severity demands it). Record
@@ -165,6 +186,7 @@ Report: the new `EP-<slug>`, its thread + parent, the re-author-vs-inherit split
 - **Never auto-advances.** This skill seeds + records; humans author and approve via the normal gates.
 
 ## Reference
+- Minting a stub genesis epic when the feature has no epic (brownfield): `../yad-stub/SKILL.md`.
 - Depth triage details, the exact seeding shape, the pointer-lock recipe, genesis migration, and the
   concurrent-change (re-parent) rule: `references/triage.md`.
 - The lineage frontmatter + ledger schemas: `../yad-epic/references/state-schema.md` (Phase 6).

package/skills/yad-epic/references/state-schema.md

@@ -263,6 +263,47 @@ locked `state.json` step shape. Genesis epics are backfilled once with `kind: fe
 | `severity` | `sev1` … `sev4` | **defect/hotfix only.** |
 | `escape_stage` | an SDLC stage id (`stories`, `test-cases`, `architecture`, …) | **defect/hotfix only.** The gate that *should* have caught it — feeds the `yad-defects` quality report. |
 | `root_cause` | short tag | **defect/hotfix only.** e.g. `missing-negative-test`. |
+| `stub` | `backfill-pending` | **stub genesis only** (`yad-stub`). A brownfield feature anchored so a change can thread off it before it is documented. Cleared by `yad-backfill promote`. |
+| `verified` | `true` \| `false` | `false` on a stub genesis (not yet documented/human-authored); `yad-backfill promote` sets it `true`. Absent ⇒ treated as a normal (verified) epic. |
+
+## Stub genesis epics (brownfield anchors — `yad-stub`)
+
+In a brownfield repo not every already-built feature has an epic, so a defect/change has no parent to
+thread from (`yad-change` requires one; `lineage-check` rejects a missing parent). `yad-stub` mints the
+smallest **real** node — a **stub genesis epic** — so the bug can be captured now and formalized later.
+
+A stub is a normal genesis (`kind: feature`, `thread == id`, no `parent`) whose `epic.md` carries
+`stub: backfill-pending` + `verified: false` and whose `state.json` uses a **sentinel**, mirroring
+`EP-discovery` / `discovery-done`:
+- top-level `kind: "stub"` and `currentStep: "backfill-pending"`;
+- the **same 10-step front chain** as a normal epic, every step `status: "blocked"` (so `validateState`
+  passes and `promote` can "wake" the chain into normal authoring with no re-seed);
+- empty `approvals.json` / `comments.json`; **no** `contract-lock.json` (no surface locked yet).
+
+`nextAction` routes a stub to a `backfill-pending` action (`yad-backfill` → `yad-backfill promote`), never
+to authoring. A change threaded off a stub inherits only what exists — the undocumented surface bases are
+marked `inherited: true` with `boundHash: null` (the gate predicate reads `null` as "nothing locked → no
+drift → pass"), no pointer-lock is written, and `change.json` records `parentStub: true`.
+
+**The stub invariant (two files, kept in lockstep).** A stub is encoded in *both* `epic.md`
+(`stub: backfill-pending`) *and* `state.json` (top-level `kind: "stub"` + `currentStep:
+"backfill-pending"`), because two readers use different sources: `isStubEpic` / `yad thread` / `yad-status`
+read the frontmatter, while `nextAction` / `yad next` is pure-ledger and reads `state.json`. So:
+
+> **A stub ⟺ `epic.md stub:backfill-pending` AND `state.kind:stub` AND `currentStep:backfill-pending`.**
+> Any promote MUST clear all three atomically, or the two readers disagree.
+
+`yad-backfill promote` enforces this: it sets `epic.md` `verified: true`, removes `stub:`, links the
+approved backfill spec, **and** rewrites `state.json` — removing `kind: "stub"` and moving `currentStep`
+off the sentinel:
+- **light promote (default)** → `currentStep: "backfill-done"`, a **terminal sentinel** (like
+  `discovery-done`): the feature is a real, verified anchor documented by its backfill spec; `nextAction`
+  reports "documented anchor — evolve it by threading a change/defect", never a pending stub, and no build
+  half runs directly against it;
+- **full promote (opt-in)** → `currentStep: "epic"`, `epic.status: "in_progress"`, to run the normal front
+  half and lock a real contract.
+
+From promotion on, the thread's contract protection is live.
 
 ## Inherited steps in `state.json`
 
@@ -324,7 +365,9 @@ Intake + triage record, one per change/defect/hotfix epic (sibling of `approvals
 
 `depth` ∈ `defect-fix | behavioral-no-surface | contract-surface | new-capability` (`config.yaml`
 `change.depths`). `defect` is `null` for a plain `change`; `hotfix` is `{ "shipFirst": true }` only for
-a `hotfix`. Thread-level rollups (`yad-timeline` / `yad-defects`) are **derived** — walk every epic
+a `hotfix`. `parentStub: true` is added when the epic threads off an un-promoted stub genesis
+(`yad-stub`) — a brownfield feature not yet documented, so no contract surface is inherited yet.
+Thread-level rollups (`yad-timeline` / `yad-defects`) are **derived** — walk every epic
 sharing `thread` and read each `change.json`; there is no duplicated thread registry.
 
 ## `reconcile-debt.json`

package/skills/yad-reconcile/SKILL.md

@@ -49,6 +49,12 @@ shipped, and pay any open debt (update the artifacts + add a regression test, th
 `reconcile-debt.json` entry `status: paid`). It never seeds the epic itself — opening a change-epic is a
 human, triaged act (`yad-change` Step 2).
 
+**Orphan code with no epic at all (brownfield):** when the drift is shipped code that belongs to a
+feature with **no owning epic in any thread**, there is nothing to thread a change off yet. Point the
+human at **`yad-stub`** first — mint a stub genesis epic (a minimal `kind: feature` thread anchor) for
+that feature — then thread the reconcile change off that stub (and run `yad-backfill` +
+`yad-backfill promote` to make the anchor real). The reconciler never mints the stub itself.
+
 ### Step 3 — `wire` (advisory CI, no block)
 Commit an advisory CI job that runs `yad reconcile --check` on push, carrying `[skip ci]` on any commit
 it makes and a concurrency group — the same loop-prevention `yad-docs-sync` uses. The job **reports**;
@@ -72,4 +78,5 @@ the reconciler is advisory.
 - The drift/refresh/wire discipline this mirrors: `../yad-docs-sync/SKILL.md`.
 - The thread model + ledgers: `../yad-epic/references/state-schema.md` (Phase 6).
 - The change-epic this hands off to: `../yad-change/SKILL.md`.
+- Anchoring brownfield code that has no epic (before a change can thread off it): `../yad-stub/SKILL.md`.
 - The gates that block at merge: `../yad-checks/` (lineage-check, epic-open, reconcile-debt).

package/skills/yad-stub/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: yad-stub
+description: '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. In a brownfield repo not every feature has an epic; yad-change requires a real parent and dead-ends without one. This skill creates the smallest real thread anchor — a tiny epic.md (kind:feature, thread:self, verified:false, stub:backfill-pending) + a seeded state.json + empty ledgers — never inventing behaviour. Defects thread off it immediately (gates pass, the bug list is derived by the thread rollup), and yad-backfill + its promote step later fill/flip it into a real feature epic. Never auto-advances. Use when the user says "there is no epic for this feature", "file a bug on a legacy feature", "anchor a brownfield feature", or when yad-change / yad-reconcile point here because a parent epic is missing.'
+---
+
+# SDLC — Stub Genesis Epic (Phase 6, the brownfield thread anchor)
+
+**Goal:** Give an **already-built feature that has no epic** the smallest node that is still *real* — a
+**stub genesis epic** — so a defect or change can thread off it right now (`yad-change` needs a real
+parent), the gates pass, and the list of linked bugs is **derived for free** by the thread rollup. The
+stub is a **thread anchor, not a spec**: it invents no behaviour. It stays `verified: false` until
+`yad-backfill` documents the feature and its `promote` step flips the stub into a real feature epic.
+
+This is the missing connective tissue in a brownfield adoption: `yad-backfill` produces a *draft spec in
+the code repo*, and `yad-reconcile` *detects* shipped code with no owning epic — but neither mints the
+hub epic a defect must thread from. `yad-stub` does exactly that, and only that.
+
+## Conventions
+
+- `{project-root}` resolves from the product hub. Epic artifacts live under
+  `{project-root}/epics/EP-<slug>/` (build plan §6), exactly like a normal genesis epic.
+- **A stub is NOT a reserved-empty id.** An epic in yad *is* a directory + `epic.md`; the tooling skips
+  any epic dir lacking `epic.md` (`threadEpics`) and `lineage-check` rejects a parent that is not a real
+  `epic.md`. So the stub is a real (if minimal) genesis — that is what makes it a valid parent.
+- The stub is a **genesis** (`kind: feature`, `thread == id`, no `parent`) — the root of a new thread.
+  Lineage frontmatter, the sentinel state, and the `stub`/`verified` fields are defined in
+  `../yad-epic/references/state-schema.md` (Phase 6 section).
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## Inputs
+
+- `feature` — **required.** The already-built feature's name (→ slugged into `EP-<slug>`).
+- `repos` — the code repo(s) this feature lives in (for the backfill boundary later).
+- `description` — one line: what the feature is (as built). **Do not** describe design or invent
+  behaviour — a stub records that the feature exists, nothing more.
+
+## On Activation
+
+### Step 1 — Confirm there really is no epic (auto-propose, human-confirm)
+Check `{project-root}/epics/` for an existing epic that already owns this feature (a genesis or any
+thread). **If one exists, STOP** and point at `yad-change` (`--parent <that epic>`) — a stub is only for
+a feature with *no* epic at all. If the code is already forward-spec'd or has a `specs/<story>/`, it is
+not a stub case either. Confirm the brownfield-no-epic situation with the human before creating anything.
+
+### Step 2 — Derive the stub epic id (engine-assigned, never by hand)
+Derive `EP-<slug>` where `slug` is **2–4 lowercase words** from the feature name (e.g.
+`EP-legacy-billing`). `EP-discovery` is **reserved** — never use it. Check `epics/` for collisions;
+append a distinguishing word if the slug exists. **The id is assigned once and never renamed** (a rename
+breaks every downstream link) — so pick from the best-known feature name and accept it as permanent.
+
+### Step 3 — Open the authoring branch
+Open `epic/EP-<slug>` per the shared "Authoring branches" procedure
+(`../yad-epic/references/state-schema.md`): git-safe (skip with a note if `{project-root}` is not a git
+work tree), check out if it exists, else create from the hub's default branch.
+
+### Step 4 — Write the stub `epic.md` (thread anchor — never invent behaviour)
+Write `{project-root}/epics/EP-<slug>/epic.md` using EXACTLY this shape:
+
+```markdown
+---
+id: EP-<slug>
+status: draft
+kind: feature            # genesis / thread root — a valid parent for lineage-check + threads
+thread: EP-<slug>        # thread == id for a genesis
+verified: false          # not a real, human-authored epic yet — a stub awaiting backfill
+stub: backfill-pending   # the honest marker; cleared on promote
+origin: brownfield
+owner:
+repos: [<the code repos this feature lives in>]
+created: <YYYY-MM-DD>
+---
+
+## Feature (stub)
+<!-- one line: what this already-built feature IS. No design, no invented behaviour. -->
+
+## Known issues
+<!-- Do not hand-maintain a list. `yad thread EP-<slug>` derives every defect/change threaded off this
+     stub from lineage — it is always current. -->
+
+## Backfill
+<!-- To make this real: run `yad-backfill` for <repo> (globs for this feature), get the spec approved
+     (verified: true), then `yad-backfill promote EP-<slug>`. -->
+```
+
+Leave `owner` for the human to set. Set `repos` to the code repo(s) the feature lives in.
+
+### Step 5 — Seed the stub `state.json` (a `backfill-pending` sentinel)
+Create `{project-root}/epics/EP-<slug>/.sdlc/state.json`. It carries the top-level marker
+`kind: "stub"` and the sentinel `currentStep: "backfill-pending"`, and the **same 10-step front chain**
+as a normal epic (`yad-epic` Step 5) but with **every step `status: "blocked"`** — so the state is valid
+(`validateState` needs a non-empty `steps` + a string `currentStep`) and `promote` can later "wake" it
+into normal authoring with zero re-seeding.
+
+```json
+{
+  "epicId": "EP-<slug>",
+  "createdAt": "<YYYY-MM-DD>",
+  "kind": "stub",
+  "currentStep": "backfill-pending",
+  "steps": [
+    { "id": "epic",               "type": "author",         "artifact": "epic.md",          "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked", "risk_tags": [] },
+    { "id": "epic-review",        "type": "review+approve", "artifact": "epic.md",          "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked", "risk_tags": [] },
+    { "id": "architecture",       "type": "author",         "artifact": "architecture.md",  "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked", "risk_tags": [] },
+    { "id": "architecture-review","type": "review+approve", "artifact": "architecture.md",  "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked", "risk_tags": ["contract"] },
+    { "id": "ui-design",          "type": "author",         "artifact": "ui-design.md",     "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked", "risk_tags": [] },
+    { "id": "ui-design-review",   "type": "review+approve", "artifact": "ui-design.md",     "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked", "risk_tags": [] },
+    { "id": "stories",            "type": "author",         "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked", "risk_tags": [] },
+    { "id": "stories-review",     "type": "review+approve", "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked", "risk_tags": [] },
+    { "id": "test-cases",         "type": "author",         "artifact": "test-cases.md",    "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked", "risk_tags": [] },
+    { "id": "test-cases-review",  "type": "review+approve", "artifact": "test-cases.md",    "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked", "risk_tags": [] }
+  ]
+}
+```
+
+Also create the empty ledgers `{.sdlc/approvals.json}` and `{.sdlc/comments.json}` (each `[]`) and the
+`reviews/` directory. **Do NOT** write a `contract-lock.json` — a stub has no locked surface yet.
+
+### Step 6 — Stop; hand off (NO auto-advance)
+Report the new `EP-<slug>`, that it is a **stub (backfill pending)**, and the two next moves:
+- **File bugs now:** `yad-change` (`--parent EP-<slug>`, `kind: defect|change`) — the defect threads off
+  the stub, its gates pass, and `yad thread EP-<slug>` lists it. A defect off a stub inherits only what
+  exists (the stub `epic.md`), re-authors its own stories/test-cases, and locks no contract (there is no
+  surface yet — see `../yad-change/SKILL.md`).
+- **Make it real later:** `yad-backfill` for the code repo, then `yad-backfill promote EP-<slug>` to flip
+  the stub to `verified: true`.
+
+Front states do not auto-advance. Suggest `yad next EP-<slug>` (prints the backfill-pending guidance) and
+`yad thread EP-<slug>` to see the anchor and everything threaded off it.
+
+## Hard rules
+
+- **A stub is an anchor, not a spec.** Never invent behaviour in `epic.md`. It records only that the
+  feature exists so a change can thread off it.
+- **Only for a feature with NO epic.** If any epic already owns the feature, use `yad-change` instead.
+- **Never `verified: true` here.** A stub is `verified: false` / `stub: backfill-pending` until
+  `yad-backfill promote` flips it — approval is earned by documenting the real code, not by minting.
+- **You never implement directly against a stub.** It owns no `stories/`, so there is nothing to
+  implement against directly — real work threads off it as a change/defect epic (which has its own
+  stories). (This is a convention of the empty stub, not a hard gate: `lineage-check` passes a
+  `kind: feature` genesis and `epic-open` treats a story-less epic as un-sealed, so neither blocks a
+  story mistakenly linked to the stub — keep the stub story-less.)
+- **Never auto-advances.** This skill seeds the anchor and stops; humans thread changes and run backfill.
+
+## Reference
+- The lineage frontmatter, the `stub`/`verified` fields, and the `kind: "stub"` /
+  `currentStep: "backfill-pending"` sentinel: `../yad-epic/references/state-schema.md` (Phase 6).
+- Threading a defect/change off the stub: `../yad-change/SKILL.md`.
+- Documenting the code + promoting the stub to real: `../yad-backfill/SKILL.md`.
+- Detecting brownfield code with no owning epic: `../yad-reconcile/SKILL.md`.