yadflow 2.16.1 → 2.18.0

package/skills/yad-checks/templates/checks/reconcile-debt-check.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# reconcile-debt gate (Phase 6 — hotfix debt). A hotfix may ship code BEFORE its front gates approve
+# (ship-first), but it opens a reconcile-debt.json entry: the front artifacts do not yet describe what
+# is in production. That debt must be PAID (artifacts updated + a regression test added) before the NEXT
+# normal change on the same feature thread can ship. This gate FAILs a non-maintenance commit whose
+# owning epic is on a thread carrying an OPEN debt that this epic does not itself own.
+#
+# Thread-scoped (only the affected thread is frozen, never the whole repo). Reads the PRODUCT repo via
+# specs/<story>/link.md `product-repo`; degrades to PASS-with-note when it is not reachable. Per commit;
+# ci/chore/build/test exempt. Fails CLOSED on an unresolvable base.
+set -euo pipefail
+
+BASE="${1:-${SDLC_BASE:-origin/main}}"
+
+if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
+  echo "FAIL [reconcile-debt]: base ref '${BASE}' not found — fetch full history / check the base branch."
+  exit 1
+fi
+RANGE="${BASE}..HEAD"
+EXEMPT='ci|chore|build|test'
+
+fm_val() { awk -v k="$1" 'NR==1 && /^---$/ {f=1; next} f && /^---$/ {exit} f && index($0, k":")==1 {sub("^" k ":[ \t]*", ""); print; exit}' "$2" 2>/dev/null | tr -d '\r'; }
+
+# Thread ROOT of an epic: walk `parent:` to the genesis (no parent). COMPUTED — never trusts the
+# denormalized `thread:` cache, so a missing/wrong cache cannot bypass the freeze. Cycle-safe.
+thread_root() {
+  prod="$1"; cur="$2"; seen=" "
+  while : ; do
+    case "$seen" in *" $cur "*) break ;; esac   # cycle guard -> stop at the last seen id
+    seen="$seen$cur "
+    em="${prod}/epics/${cur}/epic.md"
+    [ -f "$em" ] || break
+    p="$(fm_val parent "$em")"
+    [ -z "$p" ] && { printf '%s' "$cur"; return; }   # genesis reached
+    cur="$p"
+  done
+  printf '%s' "$cur"
+}
+
+# Print "epicId" for any epic that (a) belongs to the target thread — by COMPUTED membership, not the
+# debt's `thread` field — (b) is not the current epic, and (c) has an OPEN entry in its reconcile-debt
+# ledger. Because each ledger lives under exactly one epic (one thread), "this epic is on the thread AND
+# its ledger has an open status" is the correct, per-object-safe test.
+open_debt_on_thread() {
+  prod="$1"; thread="$2"; self="$3"
+  for dj in "${prod}"/epics/*/.sdlc/reconcile-debt.json; do
+    [ -e "$dj" ] || continue
+    owner_epic="$(basename "$(dirname "$(dirname "$dj")")")"   # the epic that OWNS this ledger
+    [ "$owner_epic" = "$self" ] && continue
+    [ "$(thread_root "$prod" "$owner_epic")" = "$thread" ] || continue   # computed thread membership
+    grep -q "\"status\"[[:space:]]*:[[:space:]]*\"open\"" "$dj" 2>/dev/null || continue
+    printf '%s\n' "$owner_epic"
+  done
+}
+
+commits="$(git rev-list --no-merges "$RANGE")"
+if [ -z "$commits" ]; then
+  echo "PASS [reconcile-debt]: no non-merge commits in ${RANGE}"
+  exit 0
+fi
+
+rc=0
+seen_keys=""
+while IFS= read -r sha; do
+  [ -z "$sha" ] && continue
+  short="$(git log -1 --format=%h "$sha")"
+  subject="$(git log -1 --format=%s "$sha")"
+  if printf '%s' "$subject" | grep -qE "^(${EXEMPT})(\([a-z0-9._-]+\))?!?: "; then
+    continue
+  fi
+  task="$(git log -1 --format='%(trailers:key=Task,valueonly)' "$sha" | sed '/^$/d' | head -1)"
+  printf '%s' "$task" | grep -qE '.+-T[0-9]+$' || continue
+  story="$(printf '%s' "$task" | sed -E 's/-T[0-9]+$//')"
+  link="specs/${story}/link.md"
+  [ -f "$link" ] || continue
+  product_rel="$(fm_val product-repo "$link")"
+  epic="$(fm_val epic "$link")"
+  # product-repo is relative to the link.md's directory (specs/<story>/), so join it there.
+  prod="specs/${story}/${product_rel}"
+  ep_dir="${prod}/epics/${epic}"
+  if [ -z "$product_rel" ] || [ ! -d "$ep_dir" ]; then
+    echo "PASS [reconcile-debt]: ${short} ${task} -> ${epic} (product repo not reachable — debt check deferred)."
+    continue
+  fi
+  thread="$(thread_root "$prod" "$epic")"
+  # De-dup by (thread, epic) — NOT thread alone. open_debt_on_thread excludes the CURRENT epic, so the
+  # blocker set depends on both; caching by thread would make later commits on a different epic in the
+  # same thread inherit the first epic's result (order-dependent, can miss a real block).
+  key="${thread}:${epic}"
+  case " $seen_keys " in *" $key "*) continue ;; esac
+  seen_keys="$seen_keys $key"
+  blockers="$(open_debt_on_thread "$prod" "$thread" "$epic")"
+  if [ -n "$blockers" ]; then
+    echo "FAIL [reconcile-debt]: thread ${thread} carries OPEN hotfix debt:"
+    printf '%s\n' "$blockers" | sed 's/^/    /'
+    echo "  -> Pay it first: update the front artifacts + add the regression test, then mark the"
+    echo "     reconcile-debt.json entry status: paid. The thread is frozen for new changes until then."
+    rc=1
+    continue
+  fi
+  echo "PASS [reconcile-debt]: thread ${thread} has no open hotfix debt."
+done <<EOF
+$commits
+EOF
+exit "$rc"

package/skills/yad-checks/templates/github/yad-checks.yml

@@ -34,6 +34,31 @@ jobs:
         with: { node-version: "20" }
       - run: bash checks/build-test-lint.sh
 
+  # Phase 6 — feature-thread gates. lineage-check: the change links a real threaded epic. epic-open:
+  # a sealed epic (all stories shipped) refuses new behaviour, forcing a change-epic. reconcile-debt:
+  # a thread with open hotfix debt is frozen for new changes until paid. All build on spec-link's
+  # story->epic resolution and degrade to a note when the product repo is not reachable from CI.
+  lineage-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - run: bash checks/lineage-check.sh "origin/${{ github.base_ref }}"
+
+  epic-open:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - run: bash checks/epic-open.sh "origin/${{ github.base_ref }}"
+
+  reconcile-debt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - run: bash checks/reconcile-debt-check.sh "origin/${{ github.base_ref }}"
+
   # Pattern gates: commit subject + PR title + PR body all follow the convention (profile: code).
   commit-message:
     runs-on: ubuntu-latest

package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml

@@ -53,6 +53,26 @@ yad-build-test-lint:
     - npm ci
     - bash checks/build-test-lint.sh
 
+# Phase 6 — feature-thread gates (lineage / seal / hotfix-debt). Build on spec-link's story->epic
+# resolution; degrade to a note when the product repo is not reachable from CI.
+yad-lineage-check:
+  extends: .sdlc_mr_only
+  needs: []
+  script:
+    - bash checks/lineage-check.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+
+yad-epic-open:
+  extends: .sdlc_mr_only
+  needs: []
+  script:
+    - bash checks/epic-open.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+
+yad-reconcile-debt:
+  extends: .sdlc_mr_only
+  needs: []
+  script:
+    - bash checks/reconcile-debt-check.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+
 # Pattern gates: commit subject + MR title + MR body all follow the convention (profile: code).
 yad-commit-message:
   extends: .sdlc_mr_only

package/skills/yad-defects/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: yad-defects
+description: 'Phase 6 output enrichment (never a gate) — the quality-gap report. Generates a per-epic AND per-thread defect/bug report (the vendored React/Vite/Tailwind shell HTML + a DEFECTS.md) that aggregates every kind:defect change-epic + each change.json defect block + shipped regressions in build-log.json BY escape_stage (the SDLC gate that should have caught the defect) and root_cause, and visualizes WHERE quality gaps systematically come from — e.g. "% of this feature''s defects that escaped at the test-cases gate" — so the team hardens the originating stage instead of just fixing symptoms. Degrades to markdown-only when no docs target is connected. Use when the user says "show the defect report", "where are our quality gaps", "generate the bug report for this epic", or "which gate is leaking defects".'
+---
+
+# SDLC — Quality-Gap Report (Phase 6, output enrichment)
+
+**Goal:** Turn the thread's defects into a **systemic quality signal**. Because every defect is a
+first-class `kind: defect` change-epic carrying an `escape_stage` (the gate that *should* have caught it)
+and a `root_cause`, this report can show not just *what* broke but *where the SDLC let it through* — so
+the team fixes the originating stage (weak test design, an under-specified story, a missed architecture
+risk), not just the symptom. It is an **output enrichment**, exactly like `yad-docs` — **never a gate**.
+
+## Conventions
+
+- `{project-root}` resolves from the product hub.
+- Reuses the **`yad-docs` shell** verbatim (`../yad-docs/templates/app/`) — generated `src/data/*.ts`,
+  themed, deployed via `yad docs deploy`; build-only / markdown-only when no docs target.
+- Per **epic** (one epic's defects) and per **thread** (the whole feature; the thread report lives under
+  the genesis epic, since `thread == genesis id`). The thread is derived from `parent:` frontmatter.
+- Deterministic generation, like `yad-docs` (stable sort, fixed key order, no timestamps in data).
+
+## Inputs
+
+- `epic` — scope to one epic's defects, OR `thread` — `EP-<genesis>` for the whole feature. Ask if
+  neither is given; default to the thread.
+- `action` — `generate` (default) | `deploy`.
+
+## On Activation
+
+### Step 1 — Collect the defects
+Resolve the scope (`yad thread <id> --json` for a thread). Collect, across the scoped epic(s):
+- every `kind: defect` (and `kind: hotfix`) change-epic + its `.sdlc/change.json` `defect` block
+  (`origin`, `severity`, `escape_stage`, `root_cause`);
+- the shipped regression fixes from each `.sdlc/build-log.json` (the fix that closed the defect, linking
+  the change-epic → its regression story/test);
+- open reconcile debt (a hotfix whose front truth is not yet restored).
+
+### Step 2 — Attribute each defect to the gate that should have caught it
+A defect is attributed to its **earliest** responsible SDLC stage. Use `change.json.escape_stage`
+(human-set at intake), cross-checked against the fix's shape: a missing negative test → `test-cases`; a
+wrong/absent contract field → `architecture`; an unstated acceptance criterion → `stories`; a missed
+market/requirement → `discovery`/`epic`. Record the attribution per defect.
+
+### Step 3 — Aggregate the quality signal
+Compute, for the scope:
+- **defects per escape-stage** (count + **% of scope defects** — the headline "X% escaped at the
+  `<stage>` gate");
+- **defects per root_cause**;
+- **severity mix** and **genesis→defect age** (how long after ship the defect surfaced);
+- an **escape rate** per gate = defects attributed to a stage ÷ artifacts that passed that stage (a
+  normalized "how leaky is this gate").
+
+### Step 4 — Render the report (yad-docs shell)
+Generate the site into `epics/<scope>/defects-site/` with sections:
+1. **Summary** — total defects, severity mix, escape rate.
+2. **Escape-stage breakdown** — the bar/heat view of where defects leak (the actionable headline).
+3. **Root-cause breakdown.**
+4. **Per-defect detail** — each defect linked to its change-epic and its regression test.
+5. **Severity & age.**
+6. **Recommendations** — which originating stage to harden, derived from the top escape-stages.
+
+Also write a plain `epics/<scope>/DEFECTS.md` mirror. On `action: deploy`, `yad docs deploy` the site
+(build-only when no target).
+
+## Hard rules
+
+- **Never a gate.** No writes to `state.json`, `approvals.json`, or any `contract-lock.json`. It reads
+  defect data and renders it.
+- **Attribute honestly.** Use the recorded `escape_stage`; when it is absent or contradicted by the fix,
+  cross-check and say so — do not invent an attribution.
+- **Derived + deterministic.** Re-running on unchanged data yields byte-identical output.
+- **Degrade gracefully.** No docs target → `DEFECTS.md` only; never fail because a tool is absent.
+
+## Reference
+- The defect data: `.sdlc/change.json` `defect` blocks + `build-log.json` (`../yad-epic/references/state-schema.md`, Phase 6).
+- The shell + deterministic generation it reuses: `../yad-docs/SKILL.md`, `../yad-docs/references/data-mapping.md`.
+- The companion evolution view: `../yad-timeline/SKILL.md`.
+- The intake that records `escape_stage` + `root_cause`: `../yad-change/SKILL.md`.

package/skills/yad-discovery/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: yad-discovery
+description: 'Optional front-zero of the gated SDLC — the once-per-project discovery phase. With the field-expert lenses (analyst + pm), run market research, a competitor study, a feasibility study, and (brownfield) a current-state study, then distil a functional + non-functional requirements list and a phased roadmap (MVP and beyond) into the reserved EP-discovery. Greenfield AND brownfield. Its roadmap.md becomes the menu of features each yad-epic reads. Seeds the EP-discovery state and hands off to the team review gate; never auto-advances. Use when the user says "start the project", "do discovery", "market research / feasibility / roadmap", or "what should we build first".'
+---
+
+# SDLC — Project Discovery (optional front-zero, "epic zero")
+
+**Goal:** Produce a human-authored, AI-assisted **project-level discovery set** — the field expert's
+requirement-gathering for the whole product — under the reserved `EP-discovery` ("epic zero"), then
+hand off to `yad-review-gate`. The output `roadmap.md` is the menu of features; each feature is later
+taken into the normal `yad-epic` flow, which reads the roadmap for project context.
+
+This is a **front state**: human-authored with AI assist and **never auto-advances**. It runs **once
+per project** and is **optional** — a team that already knows what to build can skip it and start at
+`yad-epic`. It supports **both greenfield and brownfield**, and produces a **competitor study in both**.
+
+This skill enforces the build plan's core rules: all state lives in files; IDs are engine-assigned
+(the reserved `EP-discovery`, never a typed feature slug); front steps are locked to `human_approve`.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory.
+- Discovery artifacts live under `{project-root}/epics/EP-discovery/` (the reserved "epic zero").
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## On Activation
+
+### Step 1 — Entry guard (runs once per project)
+The id is the reserved `EP-discovery` — never a feature slug. Discovery seeds its state exactly once:
+if `{project-root}/epics/EP-discovery/.sdlc/state.json` already exists, **STOP** and point the user at
+`yad next EP-discovery` (the phase is in review or done; edit the artifacts in place, don't re-seed).
+When no `state.json` exists yet, proceed and seed state in Step 5.
+
+Detect the project mode from `{project-root}/.sdlc/hub.json` `profile.codebase`
+(`greenfield` | `brownfield`, set by `yad setup`). If absent, ask the user; default `greenfield`.
+
+### Step 2 — Shape with the field-expert lenses (assist: analyst + pm)
+Adopt the **analyst** lens (`bmad-agent-analyst`, Mary) and the **pm** lens (`bmad-agent-pm`) to gather
+requirements as a domain expert would. Drive the existing BMAD research skills as the assist — they
+already exist in this project:
+- `bmad-market-research` — market size, segments, demand, trends, positioning.
+- `bmad-domain-research` — the problem domain, regulations, and constraints of the field.
+- `bmad-product-brief` — personas, value proposition, success metrics.
+
+Pressure-test: who are the users, what problem, what is the market, **who are the competitors and how
+do we differ** (required in BOTH modes), what is feasible, what is the smallest valuable slice (MVP),
+and what sequences after it.
+
+### Step 2b — Brownfield current-state (make discovery code-aware)
+Read the registry `{project-root}/.sdlc/repos.json` (`config.yaml` `code_context`). For **every
+connected repo**, load the lightweight code-map `{project-root}/.sdlc/code-context/<repo>/code-map.md`
+and base `current-state.md` on **what already exists** — modules, endpoints, data, gaps — so the
+roadmap extends the real system rather than re-proposing it.
+
+- **Greenfield-safe:** if `repos.json` is absent/empty (greenfield), `current-state.md` is a short
+  "clean slate / assumptions & non-goals" note, and you proceed.
+- **Staleness:** if a repo's current HEAD (`git -C <path> rev-parse HEAD`) ≠ its registry `syncedHead`,
+  warn and suggest `yad repo refresh <repo>` (a human decision — flag, never auto-refresh).
+- **Backfill pointer:** for an existing codebase, point the user at `yad-backfill` to capture specs for
+  already-built features; discovery frames the *forward* roadmap, backfill captures the *current* one.
+
+### Step 3 — Open the authoring branch
+Open the discovery authoring branch `discovery/EP-discovery` per the shared procedure
+(`../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 the discovery set on it. Distinct from the bridge's
+`review/EP-discovery/discovery` branch.
+
+### Step 4 — Write the discovery set
+Write these files under `{project-root}/epics/EP-discovery/`. Each is a normal Markdown artifact; the
+gate binds to the **whole set** (editing any one revokes approvals). `roadmap.md` summarises and links
+the others and is the spine of the review.
+
+- `market-research.md` — market, segments, demand, trends (assist: `bmad-market-research`).
+- `competitor-analysis.md` — competitors, capabilities, gaps, our differentiation (**both modes**).
+- `current-state.md` — brownfield: what exists today (Step 2b); greenfield: clean-slate assumptions.
+- `feasibility.md` — technical/operational/economic feasibility, risks, viability, go/no-go.
+- `requirements.md` — the consolidated requirements list, **functional AND non-functional**, as a
+  table (see `references/discovery-schema.md`). Functional rows are candidate features (registration,
+  login, …); non-functional rows are cross-cutting (performance, security, accessibility, i18n …).
+- `roadmap.md` — the phased plan with an explicit **MVP** phase, then later phases. Each feature row
+  carries a proposed `EP-<slug>` id, its target phase, and a `status:` of `planned`
+  (see `references/discovery-schema.md` for the exact templates).
+
+Leave `owner` for the user to set in each frontmatter. Fill the bodies with the user.
+
+### Step 5 — Seed the state machine
+Create `{project-root}/epics/EP-discovery/.sdlc/state.json` describing the **2-step** front-zero
+sequence, both steps `automation: human_approve` and `locked`, with the `kind: "discovery"` marker the
+engine keys off. Use this exact shape (see `references/discovery-schema.md`):
+
+```json
+{
+  "epicId": "EP-discovery",
+  "kind": "discovery",
+  "createdAt": "<YYYY-MM-DD>",
+  "currentStep": "discovery-review",
+  "steps": [
+    { "id": "discovery",        "type": "author",         "artifact": "discovery/", "assistance": "review", "automation": "human_approve", "locked": true, "status": "done",      "risk_tags": [] },
+    { "id": "discovery-review", "type": "review+approve", "artifact": "discovery/", "assistance": "review", "automation": "human_approve", "locked": true, "status": "in_review", "risk_tags": [] }
+  ]
+}
+```
+
+Notes:
+- The review step's artifact is the virtual base `discovery/` — the gate fingerprints the whole
+  discovery file set (`market-research`, `competitor-analysis`, `current-state`, `feasibility`,
+  `requirements`, `roadmap`), so editing any of them revokes prior approvals (mirrors `stories/`).
+  **All six must exist to review:** if any is missing the set is incomplete and non-reviewable (the
+  hash is `null`) and `yad gate open`/`sync` warn — so write all six (Step 4) before the gate.
+- `discovery-review` carries no `risk_tags` — it is the **base** rule (owner + 1 reviewer); discovery
+  never escalates to domain owners (no contract surface is touched yet).
+- Also create an empty approvals ledger `.sdlc/approvals.json` and comments ledger
+  `.sdlc/comments.json`, each containing `[]`, and the `reviews/` directory.
+
+### Step 6 — Stop at the gate (do NOT advance)
+Report: the path to the discovery set, and that the next action is **review** via `yad-review-gate`
+(base rule: owner + 1 reviewer) on the virtual artifact `discovery/`. **Never mark discovery-review
+approved here** — only real reviewers do that through the gate. When the discovery gate passes, the
+state moves to the `discovery-done` sentinel (not `ready-for-build` — discovery has no build half); the
+roadmap is now the input that each `yad-epic` reads (its "Step 2c — read the roadmap"). 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.
+
+## Reference
+- Discovery artifact templates + the 2-step state shape: `references/discovery-schema.md`.
+- State schema, chain shapes, and the authoring-branch procedure:
+  `../yad-epic/references/state-schema.md`.
+- The epic step that consumes `roadmap.md`: `../yad-epic/SKILL.md` (Step 2c).
+- Capturing already-built features in a brownfield codebase: `../yad-backfill/SKILL.md`.
+- Connecting code repos + the code-context the brain reads: `../yad-connect-repos/SKILL.md`.

package/skills/yad-discovery/references/discovery-schema.md

@@ -0,0 +1,106 @@
+# Discovery schema — artifacts + the front-zero state shape
+
+The project discovery phase ("epic zero") lives under `{project-root}/epics/EP-discovery/`. It reuses
+the per-epic ledger files (`.sdlc/state.json`, `approvals.json`, `comments.json`, `reviews/`,
+`hub-prs.json`) unchanged — `EP-discovery` is a valid epic id, so the existing gate, PR/MR bridge, CI
+sync, and `yad next` all operate on it. What is special is the `kind: "discovery"` marker on the state
+object and the 2-step chain.
+
+## State (`.sdlc/state.json`)
+
+```json
+{
+  "epicId": "EP-discovery",
+  "kind": "discovery",
+  "createdAt": "<YYYY-MM-DD>",
+  "currentStep": "discovery-review",
+  "steps": [
+    { "id": "discovery",        "type": "author",         "artifact": "discovery/", "assistance": "review", "automation": "human_approve", "locked": true, "status": "done",      "risk_tags": [] },
+    { "id": "discovery-review", "type": "review+approve", "artifact": "discovery/", "assistance": "review", "automation": "human_approve", "locked": true, "status": "in_review", "risk_tags": [] }
+  ]
+}
+```
+
+- `artifact: "discovery/"` is a **virtual** base: `artifactHash` fingerprints the whole discovery file
+  set (`discoveryHash` in `cli/epic-state.mjs`), so an edit to any discovery file revokes prior
+  approvals — exactly like `stories/` fingerprints the stories directory.
+- The **full set is required to review**: if any of the six files is missing, `discoveryHash` returns
+  `null` — the discovery is **incomplete and non-reviewable** (no hash to bind an approval to), and
+  `yad gate open` / `yad gate sync` warn with the missing filenames. Write all six (in greenfield,
+  `current-state.md` is a short clean-slate note) before handing off to the gate.
+- On approval the gate sets `currentStep: "discovery-done"` (a terminal sentinel — discovery has **no**
+  build half, so it never becomes `ready-for-build`).
+- The discovery files (relative to the epic dir) the gate commits on the review branch and re-hashes at
+  merge are: `market-research.md`, `competitor-analysis.md`, `current-state.md`, `feasibility.md`,
+  `requirements.md`, `roadmap.md` (the `DISCOVERY_FILES` list).
+
+## Artifact templates
+
+### `requirements.md`
+
+```markdown
+---
+id: EP-discovery
+artifact: requirements
+status: draft
+owner:
+---
+
+## Functional requirements
+<!-- candidate features — each becomes (or seeds) a feature epic later -->
+
+| Ref | Requirement | Description | Priority | MVP? |
+|-----|-------------|-------------|----------|------|
+| F-01 | Registration | A new user can create an account | must | yes |
+| F-02 | Login | A returning user can authenticate | must | yes |
+
+## Non-functional requirements
+<!-- cross-cutting qualities the whole product must hold -->
+
+| Ref | Category | Requirement | Target / acceptance |
+|-----|----------|-------------|---------------------|
+| N-01 | Performance | p95 page load | < 2s on 4G |
+| N-02 | Security | auth + data-at-rest | OWASP ASVS L1; encrypted at rest |
+| N-03 | Accessibility | WCAG conformance | AA |
+```
+
+### `roadmap.md` (the spine of the review)
+
+```markdown
+---
+id: EP-discovery
+artifact: roadmap
+status: draft
+owner:
+---
+
+## Summary
+<!-- the product thesis in 2–3 lines; links to market-research, competitor-analysis,
+     current-state, feasibility, requirements -->
+
+## Phase 1 — MVP
+<!-- the smallest valuable slice; the features here are built first -->
+
+| Feature | Proposed epic id | Requirements | Status |
+|---------|------------------|--------------|--------|
+| Registration | EP-registration | F-01 | planned |
+| Login | EP-login | F-02 | planned |
+
+## Phase 2 — <name>
+| Feature | Proposed epic id | Requirements | Status |
+|---------|------------------|--------------|--------|
+| … | EP-… | F-… | planned |
+
+## Later / parked
+<!-- explicitly deferred, with why -->
+```
+
+Per-feature `status:` lifecycle (set by hand): `planned` → `epic-started` (a feature epic has been
+seeded with `yad-epic`) → `shipped`. The proposed `EP-<slug>` ids are suggestions for the eventual
+`yad-epic` runs — `yad-epic` still assigns the id (and skips the reserved `EP-discovery`).
+
+The other four artifacts (`market-research.md`, `competitor-analysis.md`, `current-state.md`,
+`feasibility.md`) are free-form Markdown with a `--- id / artifact / status / owner ---` frontmatter
+block matching the two above. `competitor-analysis.md` is required in BOTH greenfield and brownfield;
+`current-state.md` is the substantive code-aware study in brownfield and a short clean-slate note in
+greenfield.

package/skills/yad-docs-overview/references/pipeline-model.md

@@ -32,6 +32,18 @@ and never gates.
 | `yad-connect-learning` | `learning.json` |
 | `yad-connect-docs` | `docs.json` |
 
+### Path: Front-zero (`phase: 0-front`)
+The OPTIONAL once-per-project discovery phase, modelled as the reserved "epic zero" `EP-discovery`.
+Greenfield AND brownfield; a 2-step author→review chain whose review binds to the whole artifact set
+and terminates at `discovery-done` (no build half).
+
+| Step (skill) | Gate | Outputs / sideEffects |
+|--------------|------|------------------------|
+| `yad-discovery` *(optional)* | → `discovery-review` (base rule) | `market-research.md`, `competitor-analysis.md`, `current-state.md`, `feasibility.md`, `requirements.md`, `roadmap.md`; seeds `EP-discovery/.sdlc/state.json` |
+
+`roadmap.md` is the menu of features each `yad-epic` reads (Step 2c) — reference-only, never
+auto-seeds epics.
+
 ### Path: Front half (`phase: 1-front`)
 The gated authoring chain + the reusable review gate (10 steps, or 12 with the optional analysis).
 
@@ -85,8 +97,8 @@ The eight yadflow lenses, each to its relevant phase sections + paths:
 
 | Lens | Relevant phases / sections |
 |------|----------------------------|
-| analyst | Setup intent, analysis step, front-half discovery |
-| pm | epic, stories, roadmap; the front gates |
+| analyst | Setup intent, project discovery (front-zero), analysis step, front-half discovery |
+| pm | project discovery (market/feasibility/roadmap), epic, stories; the front gates |
 | architect | architecture + the locked contract; escalation |
 | ux | UI design, design tool connection, the design system |
 | dev | build half: spec → implement, the per-repo loop |

package/skills/yad-epic/SKILL.md

@@ -68,10 +68,23 @@ and let it inform which `repos` the epic should touch.
 - For depth on a specific area not in the map, do a live on-demand read (see `yad-connect-repos`
   `references/code-context.md`) — do not block on it.
 
+### Step 2c — Read the project roadmap (project context, only once discovery is APPROVED)
+Consume the project front-zero (`yad-discovery`) **only after its review gate has passed** — never a
+draft or in-review roadmap (that would bypass `discovery-review`). Gate on the **state**, not file
+existence: read `{project-root}/epics/EP-discovery/.sdlc/state.json` and proceed **only when
+`currentStep == "discovery-done"`**. When it is, read its `roadmap.md` and sibling `requirements.md`
+for the project framing: which phase (MVP / later) this feature belongs to, the functional/non-functional
+requirements it carries, and how it fits the wider plan — so the epic's **Goal / Scope / Acceptance
+signals** stay consistent with the approved roadmap. **Optional & non-blocking:** if there is no
+discovery, or it has not yet reached `discovery-done` (absent / still draft / in-review), proceed
+unchanged — do not consume an unapproved roadmap. After seeding the epic, the matching roadmap row's
+`status:` can be bumped `planned → epic-started` by hand (a human edit; discovery never auto-seeds epics).
+
 ### Step 3 — Generate the Epic ID (engine-assigned, never by hand) — analysis-skipped only
 *(Skip when analysis ran — the ID was already assigned by `yad-analysis`.)*
 Derive `EP-<slug>` where `slug` is **2–4 lowercase words joined by hyphens**, drawn from the idea
-(e.g. `EP-istifta-inquiries`). Lowercase except the fixed `EP` prefix. **The ID is assigned once and
+(e.g. `EP-istifta-inquiries`). Lowercase except the fixed `EP` prefix. `EP-discovery` is **reserved**
+for the project front-zero — never use it for a feature. **The ID is assigned once and
 never renamed** — renaming breaks every downstream link (build plan §6b).
 Check `{project-root}/epics/` for collisions; if the slug exists, append a distinguishing word.
 

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

@@ -229,3 +229,109 @@ same three-way shape, anchored to each step's human gate, never self-graded):
 `machine_advance` only when its slice of `trust-log.json` (same `step`, this story's repo or the
 project) has `>= min_runs` entries AND the fraction with `verdict == "approved-unchanged"` is
 `>= min_approved_unchanged`. The dial-setter in `yad-run` enforces this; `yad-status` surfaces it.
+
+---
+
+# Phase 6 — feature threads (post-lock change management)
+
+After the contract locks and code ships, a change must not **mutate** a locked artifact (that destroys
+the lock + the audit trail). Instead every change request becomes a **new epic, threaded to its parent**
+(`config.yaml` `change:`). A feature is a **thread** of linked epics (genesis → change → defect → …); a
+change-epic **inherits** unchanged front 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, composed by the resolver (`yad-timeline`). `yad-change` seeds a change-epic;
+`yad-defects` / `yad-timeline` render the thread; `yad-reconcile` flags drift; three CI gates enforce it.
+
+## Lineage frontmatter (added to `epic.md`)
+
+An enrichment block on `epic.md` — like the `design:` / `testing:` blocks, it does **not** change the
+locked `state.json` step shape. Genesis epics are backfilled once with `kind: feature`, `thread: <self>`.
+
+| Field | Values | Meaning |
+|-------|--------|---------|
+| `kind` | `feature` \| `change` \| `defect` \| `hotfix` | Genesis is `feature` (default when absent). |
+| `thread` | `EP-<genesis>` | Stable thread id = the genesis epic's id (never renamed → stablest anchor). A **derived cache** — the authoritative thread is `parent` walked to the root; a mismatch is detectable corruption (`yad doctor`). Genesis: `thread == id`. |
+| `parent` | `EP-<slug>` | The immediate predecessor epic. **Absent ⇔ `kind: feature`.** |
+| `inherits` | subset of `[epic, architecture, contract, ui-design, stories, test-cases]` | Artifact bases carried **by reference**, not re-authored. The rest are re-authored in this epic. |
+| `supersedes` | `[EP-<slug>-S0N, …]` | Optional — specific parent story IDs this epic replaces in the head. |
+| `origin` | `production` \| `staging` \| `qa` \| `review` | **defect/hotfix only.** Where the defect was found. |
+| `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`. |
+
+## Inherited steps in `state.json`
+
+A change-epic's `state.json` is structurally identical (so `advanceState` / `nextAction` / `gatePredicate`
+/ the bridge run unchanged), but **inherited** steps are pre-marked `done` with two extra fields, and
+only re-authored steps run. The seeder sets `currentStep` to the first re-authored step.
+
+```json
+{ "id": "architecture", "type": "author", "artifact": "architecture.md",
+  "assistance": "review", "automation": "human_approve", "locked": true,
+  "status": "done", "inherited": true, "inheritedFrom": "EP-istifta-inquiries",
+  "boundHash": "sha256:…", "risk_tags": [] }
+```
+
+- `inherited` — `true` when this step's artifact is taken by reference from the thread (not authored here).
+- `inheritedFrom` — the epic in the thread that owns the referenced artifact.
+- `boundHash` — the artifact's hash at inherit time (contract surface hash for `architecture`; the
+  `storiesHash`/file hash for others). The gate predicate short-circuits an `inherited` step as
+  **satisfied** iff `boundHash` still equals the thread's current hash for that artifact — always true,
+  since the artifact lives in the parent and can't be edited from the child, so inherited steps never
+  block and are never re-reviewed.
+
+`approvals.json` gets a **provenance** record per inherited gate (not a forged approval):
+
+```json
+{ "artifact": "architecture.md", "step": "architecture-review", "status": "inherited",
+  "from": "EP-istifta-inquiries", "boundHash": "sha256:…", "date": "<YYYY-MM-DD>" }
+```
+
+## The pointer-lock — `contract-lock.json` in a change-epic
+
+When `architecture` is inherited, the seeder writes a **derived** `contract-lock.json` carrying the
+parent's hash **verbatim** so `contract-check.sh` (which reads only `hash`) passes unchanged. There is
+no `contract.md` in the child to edit, so the surface physically cannot drift.
+
+```json
+{ "artifact": "contract.md", "hash": "sha256:<parent hash, verbatim>", "lockedAt": "<date>",
+  "inheritedFrom": "EP-istifta-inquiries", "ref": "../../EP-istifta-inquiries/.sdlc/contract-lock.json" }
+```
+
+Omitting `architecture` from `inherits` (depth `contract-surface`) is what triggers a **real re-lock**:
+`yad-architecture` re-authors `contract.md`, computes a **new** hash, and `architecture-review` carries
+`risk_tags: ["contract"]` → the usual domain-owner escalation. This unifies "route back to the
+architecture gate" with "open a contract-surface change-epic" — one mechanism, not two.
+
+## `change.json`
+Intake + triage record, one per change/defect/hotfix epic (sibling of `approvals.json`).
+
+```json
+{ "epicId": "EP-istifta-queue-filter", "thread": "EP-istifta-inquiries", "parent": "EP-istifta-inquiries",
+  "kind": "defect", "depth": "defect-fix", "intakeBy": "alice", "intakeDate": "<YYYY-MM-DD>",
+  "title": "Pending queue returns answered inquiries", "description": "…",
+  "affectedArtifacts": ["stories", "test-cases"],
+  "reauthors": ["stories", "test-cases"], "inherits": ["epic", "architecture", "contract", "ui-design"],
+  "defect": { "origin": "production", "severity": "sev2", "escape_stage": "test-cases",
+              "root_cause": "missing-negative-test" },
+  "hotfix": null }
+```
+
+`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
+sharing `thread` and read each `change.json`; there is no duplicated thread registry.
+
+## `reconcile-debt.json`
+Append-only ledger of hotfix ship-first debt (a hotfix shipped code before its front gates approved).
+
+```json
+[ { "thread": "EP-istifta-inquiries", "epicId": "EP-istifta-hotfix-x", "openedDate": "<date>",
+    "reason": "prod outage", "requires": ["artifacts-updated", "regression-test"],
+    "status": "open", "paidDate": null, "paidBy": null,
+    "evidence": { "artifacts": [], "regressionTest": "" } } ]
+```
+
+`status: "open"` blocks the **next** normal change on the thread (`reconcile-debt-check.sh`) until it is
+`"paid"` (evidence: the front artifacts updated **and** a regression test added). The debt lets a hotfix
+jump the queue once, but freezes new thread work until the SDLC again describes production.