yadflow 2.17.0 → 2.18.1

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-docs-overview/SKILL.md

@@ -56,7 +56,7 @@ git work tree). Generate and commit on it.
 Map the pipeline onto the same data structures `yad-docs` uses (concrete mapping in
 `references/pipeline-model.md`):
 
-- **Flow paths** = the **phases** — `Setup`, `Front half`, `Build half`, `Automation`.
+- **Flow paths** = the **phases** — `Setup`, `Front-zero` (discovery), `Front half`, `Build half`, `Automation`, `Change management` (feature threads).
 - **Flow steps** = the **skills/gates in order** (from `module-help.csv` `preceded-by`/`followed-by`),
   each step's `messages` = the skill's `outputs`, and `sideEffects` = the `.sdlc/` files it writes.
 - **System components** = the **durable state objects** — the product hub, each `.sdlc/*.json`

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

@@ -10,7 +10,7 @@ ordering source of truth is `skills/sdlc/module-help.csv` (`phase`, `preceded-by
 
 | Shell primitive | Overview meaning |
 |-----------------|------------------|
-| `FlowPath` (`paths.ts`) | a **phase**: Setup, Front half, Build half, Automation. |
+| `FlowPath` (`paths.ts`) | a **phase**: Setup, Front-zero (discovery), Front half, Build half, Automation, Change management (feature threads). |
 | `FlowStep` (within a path) | a **skill or gate** in order; `messages` = its `outputs`; `sideEffects` = the `.sdlc/` files it writes; `status`/`bookingStatus` annotate gated vs. enrichment vs. earned. |
 | `SystemComponent` (`components.ts`) | a **durable state object** (the hub, each `.sdlc/*.json`, code repos, the design/testing/learning tools, the platform). |
 | `RoleConfig` (`roles.ts`) | a **lens** → its relevant sections + paths. |
@@ -66,7 +66,7 @@ Per-story, per-repo: `spec → tasks → implement → checks → engineer-revie
 |--------------|------------------------|
 | `yad-spec` | `specs/<story-id>/` (Spec Kit layout), `link.md` |
 | `yad-implement` | a branch + commit per atomic task |
-| `yad-checks` | `checks/*.sh`, CI workflows |
+| `yad-checks` | `checks/*.sh`, CI workflows — the gate set: `spec-link · contract-check · build-test-lint · verified-commits · commit-message · pr-title · pr-template · lineage-check · epic-open · reconcile-debt` |
 | `yad-pr-template` | PR/MR template + routing helpers |
 | `yad-commit` / `yad-open-pr` / `yad-ship` | one commit / one PR/MR |
 | `yad-engineer-review` | engineer review + ship recorded in `build-log.json` |
@@ -83,11 +83,30 @@ node classes from the diagram.
 | `yad-status` | read-only view (no writes) |
 | `yad-docs` / `yad-docs-overview` / `yad-docs-sync` | the docs sites + their `docs-build.json` manifests |
 
+### Path: Change management — feature threads (`phase: 6-change`)
+The post-lock evolution layer. Once an epic is **sealed** (all stories shipped), behaviour can no longer
+be mutated in place — a change request becomes a **new epic threaded to its parent** (genesis → change →
+defect), inheriting unchanged front artifacts **by reference** and re-authoring only what changes, so
+locked artifacts are never mutated and never go stale, only superseded. Three CI gates enforce the thread
+(`lineage-check`, `epic-open`, `reconcile-debt`). This path never gates the front chain; `yad-change` is
+the intake, then it hands off to the normal authoring skills + the review gate.
+
+| Step (skill) | Outputs / sideEffects |
+|--------------|------------------------|
+| `yad-change` | intake + triage depth (defect-fix / behavioral-no-surface / contract-surface / new-capability); seeds a threaded change-epic — lineage frontmatter, inherited-step `state.json`, pointer-lock `contract-lock.json`, `change.json`, and `reconcile-debt.json` for hotfixes |
+| `yad-timeline` | `TIMELINE.md` (the thread evolution view) + `thread-resolved.md` (the resolved current truth) |
+| `yad-defects` | `DEFECTS.md` (quality-gap report by `escape_stage` + root cause) |
+| `yad-reconcile` | advisory drift / orphan / debt sweep (read-only; mirrors `yad-docs-sync`) |
+
+CLI: `yad thread [<epic>]` prints a thread + its resolved current truth + open debt; `yad reconcile`
+runs the sweep. The three thread gates ride in the build-half `yad-checks` set above.
+
 ## System components = the durable state objects
 
 `components.ts` renders these on the canvas (deterministic positions): the **product hub**; each
 `.sdlc/*.json` (`state.json`, `approvals.json`, `comments.json`, `hub.json`, `repos.json`, `design.json`,
-`testing.json`, `learning.json`, `docs.json`, `contract-lock.json`, `build-state/*`, `trust-log.json`);
+`testing.json`, `learning.json`, `docs.json`, `contract-lock.json`, `build-state/*`, `trust-log.json`,
+and the change-thread ledgers `change.json`, `reconcile-debt.json`, `build-log.json`);
 the **connected code repos**; the **design / testing / learning tools**; and the **platform**
 (GitHub/GitLab + Pages). A skill's `sideEffects` link its step to the component it writes.
 

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.

package/skills/yad-reconcile/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: yad-reconcile
+description: 'Phase 6 maintenance/CI — the change reconciler (mirrors yad-docs-sync; NEVER a gate). Detects post-lock DRIFT and ORPHANS across feature threads: shipped code or a repo HEAD advance (the repos.json syncedHead-vs-current-HEAD rule) with NO owning change-epic in any thread, a broken lineage (cycle, missing parent, or a thread cache that disagrees with the computed root), and open hotfix reconcile debt — reporting which thread drifted and WHY. `check` (default, read-only) reports; `refresh` points the human at opening a reconcile change-epic with yad-change (never silent); `wire` commits an advisory CI job ([skip ci] + concurrency, like yad-docs-sync) that runs the check on push. The hard merge BLOCK is the lineage-check / epic-open / reconcile-debt CI gates — this only DISCOVERS. Use when the user says "reconcile the changes", "check for thread drift", "is anything shipped without an epic", or "find open hotfix debt".'
+---
+
+# SDLC — Change Reconciler (Phase 6, the drift/orphan sweep)
+
+**Goal:** Keep the feature threads honest the way `yad-docs-sync` keeps the doc sites honest — by
+**detecting drift, not authoring**. It answers: is any shipped code missing an owning change-epic in a
+thread? Is any lineage broken? Is any hotfix debt still open (freezing the next change)? It **reports**;
+the human decides. It is **never a gate** — it never touches `state.json`, approvals, or the contract
+lock. The hard enforcement is the CI gates (`lineage-check`, `epic-open`, `reconcile-debt`); this skill
+is the read-only counterpart that surfaces problems *before* a PR hits those gates.
+
+## Conventions
+
+- `{project-root}` resolves from the product hub.
+- It drives the **`yad reconcile` CLI** (`cli/thread.mjs`): `yad reconcile [check|refresh|wire]
+  [--thread EP-<genesis>]`. The CLI is the engine; this skill orchestrates + explains.
+- The thread is **derived** from `parent:` frontmatter (no registry). Repo drift uses the exact
+  `repos.json` `syncedHead`-vs-current-HEAD rule (`config.yaml` `code_context.staleness: head-sha`),
+  reused from `yad-docs-sync` / `yad repo`.
+- Refresh is **never silent** — it points at `yad-change`, the same discipline as `yad repo refresh`.
+
+## Inputs
+
+- `action` — `check` (default, read-only) | `refresh` | `wire`.
+- `thread` — optional `EP-<genesis>` to scope to one feature thread; default sweeps every thread.
+
+## On Activation
+
+### Step 1 — `check` (default, read-only) — detect drift + orphans + debt
+Run `yad reconcile check` (optionally `--thread EP-<genesis>`). For each thread it reports, in
+`yad check` drift style, any of:
+- **Broken lineage** — a change-epic whose `parent` is missing, a cycle, or a `thread` cache that
+  disagrees with the computed root (the same signal `yad doctor` reports).
+- **Orphan / drift** — code shipped (`build-log.json`) or a touched repo's HEAD advanced past its
+  `repos.json` `syncedHead` with **no owning change-epic** in any thread — i.e. behaviour reached
+  production that no epic in the thread describes. Name the repo (`<repo>: <old>→<new>`).
+- **Open hotfix debt** — a `reconcile-debt.json` entry still `open`; the next normal change on that
+  thread is blocked until it is paid.
+
+Writes nothing. This is the read-only sweep a human (or CI) runs to see the picture.
+
+### Step 2 — `refresh` (advisory, never silent)
+For each flagged thread, **point the human at the fix** — open a reconcile change-epic with `yad-change`
+(`kind: change`, threaded to the affected feature) to bring the front artifacts back in step with what
+shipped, and pay any open debt (update the artifacts + add a regression test, then set the
+`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).
+
+### 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**;
+it never blocks. The blocking enforcement is the `yad-checks` gates, not this.
+
+### Step 4 — Report
+Summarise per thread: clean, or the concrete drift/debt found and what to do. Never advance any epic;
+the reconciler is advisory.
+
+## Hard rules
+
+- **Never a gate.** It never touches `state.json`, `approvals.json`, or any `contract-lock.json`. Drift
+  blocks nothing here — it only flags. The CI gates do the blocking.
+- **Reconcile, don't author.** It detects; opening a change-epic is delegated to `yad-change` (a human,
+  triaged act). `refresh` is never silent.
+- **HEAD-sha drift, reused.** Repo drift uses the exact `repos.json` `syncedHead` rule, like
+  `yad-docs-sync` and `yad repo`.
+- **Loop-prevention in CI.** The wired job carries `[skip ci]` + a concurrency group.
+
+## Reference
+- 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`.
+- The gates that block at merge: `../yad-checks/` (lineage-check, epic-open, reconcile-debt).

package/skills/yad-timeline/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: yad-timeline
+description: 'Phase 6 output enrichment (never a gate) — render a feature THREAD as an evolution view AND resolve its current truth. Walks the thread (genesis -> changes -> defects, linked by parent: frontmatter), renders the evolution as the vendored React/Vite/Tailwind shell HTML + a TIMELINE.md summary (each node: kind, what it re-authored vs inherited, ship events, contract re-lock history, open debt), and emits thread-resolved.md — the composed CURRENT-TRUTH map (the latest epic that owns each artifact + the resolved contract-lock hash). That resolved map is the source-of-truth AI/humans read to plan the next change, instead of a stale genesis epic. Degrades to markdown-only when no docs target is connected. Use when the user says "show the feature timeline", "how did this feature evolve", "resolve the current truth", or "render the thread".'
+---
+
+# SDLC — Feature Timeline + Current-Truth Resolver (Phase 6, output enrichment)
+
+**Goal:** Make a feature's *evolution* legible and its *current truth* explicit. A feature is a thread of
+linked epics; this skill renders that thread (genesis → changes → defects) as an interactive evolution
+view and resolves the inheritance chain into the authoritative **current artifact set** — so an AI or a
+human planning the next change reads *what the feature actually is now*, not a superseded genesis epic.
+It is an **output enrichment**, exactly like `yad-docs` — **never a gate**: it never touches
+`state.json`, approvals, or the contract lock.
+
+## 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
+  (`.sdlc/docs.json`). The resolver part drives the **`yad thread` CLI** (`cli/thread.mjs`).
+- The thread is **derived** from `parent:` frontmatter (no registry). The thread report lives under the
+  **genesis** epic (`thread == genesis id`).
+- Deterministic generation (stable-id sort, fixed key order, no timestamps in data files), like
+  `yad-docs`, so an unchanged thread re-renders byte-identically.
+
+## Inputs
+
+- `thread` — `EP-<genesis>` (or any epic in the thread; it resolves to the root). Ask if not given.
+- `action` — `generate` (default) | `deploy`.
+
+## On Activation
+
+### Step 1 — Resolve the thread
+Run `yad thread <thread> --json` (`resolveThread` + `threadEpics` + `resolveCurrentArtifacts`). This
+gives the genesis-first chain, each epic's lineage (`kind`, `parent`, `inherits`), the resolved
+current-truth map, and any open reconcile debt. **STOP** and report if the lineage is broken (point at
+`yad doctor` / `yad-reconcile`).
+
+### Step 2 — Read each node's evolution facts
+For each epic in the chain read `epic.md` (lineage + the change brief), `.sdlc/change.json` (depth,
+defect block), `.sdlc/build-log.json` (ship events), and the contract-lock (a real lock = a re-lock
+event; a pointer-lock = inherited). Greenfield-safe: an absent input degrades its part of the view.
+
+### Step 3 — Render the evolution view (yad-docs shell)
+Generate the site into `epics/<thread>/timeline-site/` (copy the shell verbatim; generate `src/data/*.ts`
+deterministically; theme from the design system). The thread maps onto the shell primitives:
+- **Flow path** = the thread; **flow steps** = the epics in order (genesis → tip), each step's messages
+  = what it re-authored, its side-effects = the ships it produced + any contract re-lock.
+- **System components** = the artifacts (epic/architecture/contract/ui/stories/test-cases), each labelled
+  with the epic that currently **owns** it (from the resolved map).
+- Colour nodes by `kind` (feature/change/defect/hotfix); mark sealed epics and open debt.
+
+### Step 4 — Emit `thread-resolved.md` (the current-truth map — derived, non-authoritative)
+Write `epics/<thread>/thread-resolved.md`: for each artifact base, the **owning epic** (the latest in the
+chain that re-authored it) and, for the contract, the **resolved lock hash**. Mark it clearly as a
+*derived, regenerable* file (it is composed from immutable artifacts; it is not itself an artifact). This
+is the file the next `yad-change` / `yad-epic` reads as "the feature's current truth".
+
+### Step 5 — Emit `TIMELINE.md` + (optional) deploy
+Write a short `epics/<thread>/TIMELINE.md` (the chain, what each node changed, ships, open debt) for a
+plain-text read. 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
+  the thread and renders it.
+- **Derived, regenerable.** `thread-resolved.md` and the site are composed from immutable artifacts;
+  re-running yields byte-identical output. They are enrichment, never the source of approval.
+- **Degrade gracefully.** No docs target → markdown-only (`TIMELINE.md` + `thread-resolved.md`); never
+  fail because a tool is absent.
+
+## Reference
+- The resolver + thread engine: `cli/thread.mjs` (`yad thread`), `cli/epic-state.mjs`
+  (`resolveThread` / `resolveCurrentArtifacts`).
+- The shell + deterministic generation it reuses: `../yad-docs/SKILL.md`,
+  `../yad-docs/references/data-mapping.md`.
+- The thread model + ledgers: `../yad-epic/references/state-schema.md` (Phase 6).
+- The companion report: `../yad-defects/SKILL.md`.