yadflow 2.16.1 → 2.18.0

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`.