yadflow 1.0.1

package/skills/sdlc-spec/references/spec-handoff.md

@@ -0,0 +1,101 @@
+# Spec Kit handoff — command list, output map, and degradation rules
+
+Step A (`sdlc-spec`) runs the **heavy Spec Kit ceremony once per story per repo** and writes the
+result into the story's code repo. This reference pins the exact commands, the files they produce, and
+how to hand-author the same files faithfully when Spec Kit is not installed — so Step B
+(`sdlc-implement`, not built yet) can read them unchanged.
+
+## The ceremony (run once, in order)
+
+Driven as harness slash-commands (RESEARCH-NOTES §2, Deviation 3), from **inside** the code repo:
+
+| # | Command | Purpose | Writes |
+|---|---------|---------|--------|
+| 1 | `/speckit.specify`   | Turn the story into a spec | `specs/<feature-id>/spec.md` (+ `research.md`, `data-model.md`, `contracts/`) |
+| 2 | `/speckit.clarify`   | Resolve ambiguities; tighten the spec | updates `spec.md` |
+| 3 | `/speckit.plan`      | Technical approach for this repo | `specs/<feature-id>/plan.md` |
+| 4 | `/speckit.analyze`   | Cross-check spec ↔ plan consistency | updates `spec.md`/`plan.md` |
+| 5 | `/speckit.checklist` | Quality checklist for the spec | checklist section under `specs/<feature-id>/` (in the degraded path, folded into `spec.md`) |
+| 6 | `/speckit.tasks`     | Atomic task list | `specs/<feature-id>/tasks.md` |
+
+**Excluded from Step A:** `/speckit.constitution` (project-level, one-time bootstrap) and
+`/speckit.implement` (that is Step B — the per-task build loop). Stop at `tasks`.
+
+**Feature-id is pinned** to the story ID (`EP-<slug>-S0N`), never Spec Kit's numbered auto-slug. If a
+Spec Kit version forces its own folder name, keep the run but make `link.md` (below) the crosswalk
+between the Spec-Kit slug and the permanent story ID.
+
+## Output map (what must exist after Step A)
+
+```
+demo-repos/<repo>/specs/<story-id>/
+  spec.md         # the feature spec — what to build & why, traced to acceptance criteria
+  research.md     # decisions/unknowns resolved during clarify
+  data-model.md   # entities/fields THIS repo implements (quoting the shared ones from the contract)
+  contracts/      # the API/event surface this repo implements (quoted from the locked contract)
+  plan.md         # technical approach for this repo
+  tasks.md        # numbered atomic tasks (T01…), each scoped to the files it may touch
+  link.md         # back-pointer to the story in the product repo (Step A adds this; not a Spec Kit file)
+```
+
+## Degradation rules (when Spec Kit is not installed)
+
+Author each file by hand so it is **indistinguishable in shape** from a real Spec Kit run. The content
+comes from the story's acceptance criteria and the **locked contract surface** — never invented.
+
+- **`spec.md`** — restate the story as a spec: context, the user/system need, in-scope behavior,
+  out-of-scope, and acceptance criteria copied verbatim from the story. Reference (do not redefine) the
+  contract endpoints/entities the story touches.
+- **`research.md`** — list the decisions and any unknowns; if the story is unambiguous, say so. Note
+  where the contract already settles a question (e.g. status is server-owned).
+- **`data-model.md`** — the entities/fields **this repo** implements. Shared entities (e.g. `Inquiry`,
+  `InquiryStatus`) are **quoted from the contract** and marked as contract-owned; repo-private fields
+  are marked as local.
+- **`contracts/`** — the slice of the API/event surface this repo implements, **quoted from the locked
+  `contract.md`** (e.g. `POST /inquiries` request/response). Add a one-line note that this is a quote of
+  the locked surface, not a new definition.
+- **`plan.md`** — the technical approach for this repo at story altitude (components, sequence,
+  test approach). No new cross-repo surface.
+- **`tasks.md`** — numbered atomic tasks. Each task: an ID (`T01`, `T02`, …), a one-line goal, and an
+  explicit **Files** list naming the files it may touch (≤3 where possible). This is what Step B reads
+  to enforce "the diff stays inside the files the task declared."
+
+## link.md template
+
+```markdown
+---
+story: EP-<slug>-S0N
+epic: EP-<slug>
+repo: <repo>
+feature-id: EP-<slug>-S0N
+product-repo: <absolute or relative path to the product repo>
+contract-lock: sha256:<hex copied from epics/EP-<slug>/.sdlc/contract-lock.json>
+speckit: installed | not-installed
+generated: <YYYY-MM-DD>
+---
+
+# Spec link — EP-<slug>-S0N (<repo>)
+
+This spec implements story **EP-<slug>-S0N** of epic **EP-<slug>** for the **<repo>** repo.
+
+- Story: `<product-repo>/epics/EP-<slug>/stories/EP-<slug>-S0N.md`
+- Contract (locked, singular): `<product-repo>/epics/EP-<slug>/contract.md`
+- Contract surface hash at spec time: `sha256:<hex>` (copied from the lock, not recomputed here)
+
+The contract surface above is **referenced, not re-defined**. Any change to the shared surface must go
+back to the architecture gate in the product repo — it is never widened from this code repo.
+```
+
+## Do not re-invent the contract
+
+The spec **quotes** the locked surface; it never extends it. To confirm the surface the spec relies on
+matches the lock, run from the **product** repo:
+
+```bash
+awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' \
+  epics/EP-<slug>/contract.md | shasum -a 256
+# compare against epics/EP-<slug>/.sdlc/contract-lock.json
+```
+
+If the story needs surface that is not in the locked block, STOP and route back to the architecture
+gate. Step A never re-locks or widens the contract.

package/skills/sdlc-status/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: sdlc-status
+description: 'Read-only view of an SDLC epic: prints the current step, each step''s dials (assistance/automation) and status, and which approvals are still required at the active gate. For stories in the build half it also prints each back-half step''s automation dial, status, and trust record (runs / % approved-unchanged / whether it clears the threshold to be earned), plus the system-wide kill-switch state — so the team can see WHY a step is automated and reverse it with evidence. Surfaces the Phase 5 instrumentation signals: per-step "earned but manual" (nudge cost) and, across multiple epics, a fleet roll-up (scale of read). Use when the user says "sdlc status", "where is epic EP-...", "what is blocking the gate", "show the trust record", or "fleet status".'
+---
+
+# SDLC — Status (read-only)
+
+**Goal:** Make the file-driven state legible at a glance. This skill **never writes** — it only
+reads `.sdlc/` and `reviews/` and reports.
+
+## Conventions
+- `{project-root}` resolves from the project working directory.
+- Operate on one epic: `{project-root}/epics/EP-<slug>/`.
+
+## On Activation
+
+### Step 1 — Resolve the epic
+If no `EP-<slug>` was given, list the epics under `{project-root}/epics/` and ask which one (or
+report all if the user asked for an overview).
+
+### Step 2 — Read state
+Read `.sdlc/state.json`, `.sdlc/approvals.json`, `epic.md` frontmatter (for `repos`), and — if present
+— `.sdlc/contract-lock.json`. For the build half (Phase 4), also read — if present — every
+`.sdlc/build-state/<story-id>.json`, `.sdlc/trust-log.json`, and the `automation` block of
+`skills/sdlc/config.yaml` (`back_steps`, `trust_threshold`, `locked_steps`, `kill_switch`). Do not
+modify any of them.
+
+### Step 3 — Report
+Print, in this order:
+
+1. **Epic:** `epicId`, `status` from `epic.md` frontmatter, `currentStep`, and `repos` (the touched
+   domains).
+2. **Steps table** — for every front step in `steps[]` order (8, or 10 when the optional analysis step
+   was run): `id`, `type`, `status`, `assistance`, `automation`, `locked`, and `risk_tags`. Mark the
+   `currentStep` with `→`. The full front-state chain is `[analysis → analysis-review →] epic →
+   epic-review → architecture → architecture-review → ui-design → ui-design-review → stories →
+   stories-review` (then `ready-for-build`); the bracketed `analysis` prefix is present only when
+   `sdlc-author-analysis` seeded it. Always render exactly the steps present in `steps[]`.
+3. **Active gate** — for the `currentStep` (if it is a `review+approve` step), compute and show:
+   - the reviewer rule in force — **base** (`owner + 1 reviewer`), **escalated** (list the required
+     domains), or **per-repo** for `stories-review` (list each repo needing sign-off),
+   - approvals **recorded so far** (from `approvals.json`), and
+   - approvals **still required** to pass the gate (name the missing domains/repos).
+   Do not advance — just state whether the gate would pass right now.
+
+   Apply the same predicate `sdlc-review-gate` uses (restated here so this skill is
+   self-contained). From the `approved` records in `approvals.json` for the current step:
+   - `owners` = records with `role == "owner"`; `reviewers` = distinct `role == "reviewer"`;
+     `domainOwners` = `role == "domain-owner"`, grouped by `domain`.
+   - **Base pass:** `|owners| >= 1` AND `|reviewers| >= 1` (the configured `default_reviewers`).
+   - **Escalated pass** (step `risk_tags` ∩ `{contract, auth, payments}` ≠ ∅): base pass AND, for
+     every touched domain, `|domainOwners[domain]| >= 1`. Touched domains = `epic.repos` for
+     `architecture-review`; the union of every story's `repos` for `stories-review`.
+   - Approvals are **stale** (gate fails) if the artifact was edited after the newest `approved`
+     record. For `architecture-review`, also flag staleness if the contract-surface hash no longer
+     matches `.sdlc/contract-lock.json`.
+4. **Contract lock** — if `.sdlc/contract-lock.json` exists, show the locked hash and `lockedAt`
+   (and, when at/after `architecture-review`, whether the current surface still matches it).
+5. **Stories** — if `stories/` has files, list each story `id` and its `repos` tags.
+6. **Files** — list the review records present under `reviews/` for the current artifact.
+7. **Build half (per story, per repo)** — if any `.sdlc/build-state/<story-id>.json` exists, then for
+   each such story and each of its repos print the back-half chain
+   `spec → tasks → implement → checks → engineer-review`, marking each step's `status`, its
+   `automation` dial, and `locked`. Mark that repo's `currentStep` with `→`. This shows, at a glance,
+   which back steps are automated and where a run is waiting.
+8. **Automation & trust** — print the system-wide **kill switch** state from `config.yaml`
+   `automation.kill_switch` (when `on`, note that every step is forced to `human_approve`). Then, for
+   each back-half step that has entries in `.sdlc/trust-log.json`, print its **trust record**: number
+   of runs, the fraction with `verdict == "approved-unchanged"`, and whether that clears
+   `automation.trust_threshold` (`min_runs`, `min_approved_unchanged`) — i.e. whether the step is
+   **earned** (eligible to be flipped to `machine_advance`) or still **gathering evidence**. Restate
+   the predicate (self-contained): `earned = runs >= min_runs AND unchanged/runs >= min_approved_unchanged`.
+   Never recommend flipping a locked step or a front state — those can never be `machine_advance`.
+
+   **Nudge-cost signal (Phase 5 instrumentation).** For each back step that is **earned but its dial
+   is still `human_approve`** (and it is not locked / not a front state), flag it:
+   `⚠ earned but manual — could be machine_advance`. This is the *nudge cost* the Phase 5 trigger
+   watches: automation that is proven safe but still hand-started. It is a read-only observation, not a
+   recommendation to flip — earning the evidence and flipping the dial stay deliberate human acts
+   (`sdlc-run action: set-dial`). See `docs/phase-5-build-plan.md` §"What to instrument now".
+
+9. **Fleet roll-up (overview only).** When the user asked for an overview, or more than one epic exists
+   under `{project-root}/epics/`, print a one-line-per-epic roll-up across the fleet: each epic's
+   `currentStep` (front gate) and, for stories in the build half, a count of back-half steps **waiting
+   at a human gate** and of steps flagged **earned-but-manual**. Close with fleet totals (epics at each
+   front gate; total earned-but-manual back steps). This is the *scale-of-read* signal the Phase 5
+   trigger watches — when this roll-up stops fitting in one glance, that is the measured bottleneck.
+   Still strictly read-only; it only scans the per-epic files.
+
+### Hard rule
+This skill is strictly read-only. If the user wants to comment, approve, or advance, point them to
+`sdlc-review-gate`.