yadflow 4.6.0 → 4.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/CHANGELOG.md +170 -0
  2. package/README.md +4 -1
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +167 -15
  5. package/cli/artifact-status.mjs +88 -20
  6. package/cli/build.mjs +1372 -0
  7. package/cli/checkpoint.mjs +2 -2
  8. package/cli/commit.mjs +1 -0
  9. package/cli/dial.mjs +21 -1
  10. package/cli/docs.mjs +6 -1
  11. package/cli/doctor.mjs +133 -26
  12. package/cli/epic-state.mjs +357 -9
  13. package/cli/errors.mjs +2 -0
  14. package/cli/find-product.mjs +36 -2
  15. package/cli/fold.mjs +9 -5
  16. package/cli/gate-local.mjs +9 -1
  17. package/cli/gate.mjs +364 -22
  18. package/cli/history.mjs +22 -2
  19. package/cli/hook.mjs +3 -1
  20. package/cli/index-command.mjs +2 -2
  21. package/cli/ledger.mjs +60 -0
  22. package/cli/next.mjs +34 -11
  23. package/cli/openpr.mjs +81 -5
  24. package/cli/platform.mjs +21 -0
  25. package/cli/pr-list.mjs +5 -3
  26. package/cli/product-index.mjs +6 -3
  27. package/cli/product-token.mjs +186 -0
  28. package/cli/productcommit.mjs +33 -0
  29. package/cli/recommend.mjs +3 -1
  30. package/cli/repo-publish.mjs +2 -2
  31. package/cli/run-checks.mjs +586 -0
  32. package/cli/ship-drift.mjs +49 -18
  33. package/cli/standup.mjs +1 -1
  34. package/cli/status.mjs +282 -0
  35. package/cli/test-build.mjs +1559 -0
  36. package/cli/test-run-checks.mjs +603 -0
  37. package/cli/test-worktree.mjs +520 -0
  38. package/cli/thread.mjs +4 -0
  39. package/cli/tidy.mjs +2 -2
  40. package/cli/toolbox.mjs +36 -5
  41. package/cli/workspace.mjs +4 -1
  42. package/cli/worktree-record.mjs +53 -0
  43. package/cli/worktree.mjs +379 -0
  44. package/package.json +3 -3
  45. package/skills/sdlc/config.yaml +1 -1
  46. package/skills/sdlc/module-help.csv +1 -1
  47. package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
  48. package/skills/yad-change/SKILL.md +3 -0
  49. package/skills/yad-checks/SKILL.md +34 -5
  50. package/skills/yad-checks/references/check-gates.md +69 -10
  51. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  52. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  53. package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
  54. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  55. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  56. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  57. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  58. package/skills/yad-checks/templates/checks/package-manager.sh +41 -4
  59. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  60. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  61. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  62. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  63. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  64. package/skills/yad-checks/templates/github/yad-checks.yml +8 -8
  65. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
  66. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
  67. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  68. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  69. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  70. package/skills/yad-commit/SKILL.md +4 -2
  71. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  72. package/skills/yad-docs/templates/app/package.json +2 -2
  73. package/skills/yad-engineer-review/SKILL.md +45 -20
  74. package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
  75. package/skills/yad-epic/references/state-schema.md +75 -16
  76. package/skills/yad-implement/SKILL.md +75 -13
  77. package/skills/yad-implement/references/implement-conventions.md +8 -1
  78. package/skills/yad-implement/templates/.gitmessage +3 -0
  79. package/skills/yad-open-pr/SKILL.md +21 -0
  80. package/skills/yad-pr-template/SKILL.md +6 -2
  81. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  82. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  83. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  84. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  85. package/skills/yad-product-bridge/SKILL.md +14 -1
  86. package/skills/yad-product-bridge/references/bridge.md +5 -2
  87. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  88. package/skills/yad-reconcile/SKILL.md +9 -3
  89. package/skills/yad-review-gate/SKILL.md +4 -0
  90. package/skills/yad-review-gate/references/gating.md +26 -1
  91. package/skills/yad-run/SKILL.md +52 -28
  92. package/skills/yad-run/references/run-loop.md +42 -21
  93. package/skills/yad-spec/SKILL.md +137 -16
  94. package/skills/yad-spec/references/spec-handoff.md +50 -3
  95. package/skills/yad-status/SKILL.md +7 -0
  96. package/skills/yad-stories/references/story-schema.md +1 -1
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: yad-spec
3
- description: 'Build Step A of the gated SDLC. For one ready-for-build story and one of its repos, run the heavy Spec Kit ceremony ONCE (specify → clarify → plan → analyze → checklist → tasks) inside that code repo, writing specs/<story-id>/ in Spec Kit''s own layout. Drives /speckit.* as harness slash-commands when installed; authors the same files by hand and records speckit: not-installed when absent. References the locked contract — never re-invents the surface. Writes link.md back to the story. Never auto-advances. Use when the user says "spec story <id> in <repo>" or after a story is ready-for-build.'
3
+ description: 'Build Step A of the gated SDLC. For one ready-for-build story and one of its repos, run the heavy Spec Kit ceremony ONCE (specify → clarify → plan → analyze → checklist → tasks) inside that code repo, writing specs/<story-id>/ in Spec Kit''s own layout. Drives /speckit.* as harness slash-commands when installed; authors the same files by hand and records speckit: not-installed when absent. References the locked contract — never re-invents the surface. Writes link.md back to the story. For a small story with no contract surface, offers a light spec (one spec.md with the plan and tasks) that a human confirms (#348). Never auto-advances. Use when the user says "spec story <id> in <repo>" or after a story is ready-for-build.'
4
4
  ---
5
5
 
6
6
  # SDLC — Author Spec (Build Step A)
@@ -43,7 +43,7 @@ Tell the person which tools you used and which fallbacks, and why.
43
43
 
44
44
  - **Spec Kit** (`spec-kit`). Use it when its entry has `used: true` and `status.state` is `installed` or `available`. Otherwise — not found, its plugin turned off in Claude Code, or the team chose not to use it (`yad toolbox remove spec-kit`) — use the fallback.
45
45
  - Fallback — yad-spec writes the same spec files by hand, in Spec Kit's layout.
46
- - Record `speckit: not-installed`. It means the tool was not used, whatever the reason.
46
+ - Record `speckit: not-installed`. It means the tool was not used, whatever the reason — except a light spec, which never runs Spec Kit and records `speckit: not-used` (#348).
47
47
 
48
48
  <!-- end: When a tool is missing -->
49
49
 
@@ -68,6 +68,45 @@ Tell the person which tools you used and which fallbacks, and why.
68
68
  - `repo` — one entry from that story's `repos` (the ONE repo to spec; ask if the story lists more
69
69
  than one).
70
70
 
71
+ ## Ask the human-only questions first, in one batch
72
+
73
+ <!-- The same section is in yad-spec and yad-implement: a test holds the two copies equal (#357). -->
74
+
75
+ Some decisions belong to the human alone. If one turns up late, the long work stops and waits for it.
76
+ So before the long work starts, list every such decision together with every open question, and ask
77
+ them all in **one** message.
78
+
79
+ **Human-only decisions** — never decide these yourself, and never pick a default just to keep going:
80
+ - **Security trade-offs.** Who may call or see what, what data is stored, logged or shown, how
81
+ people sign in, and any check made weaker on purpose.
82
+ - **Secrets and tokens.** Which secret or token the work needs, who creates it, where it is kept,
83
+ and what it may access.
84
+ - **Contract changes.** The work needs the shared cross-repo surface (the locked `contract.md`) to
85
+ change. Nobody decides this here, and no answer lets the step go on: it goes back to the
86
+ architecture gate, or, on a short lane, to a new epic on `classic`. Name it in the batch so the
87
+ person learns it now, not halfway through. Then end the step with this skill's own contract STOP
88
+ (`yad-spec` Step 3, `yad-implement` Step 5), and its `contract touch` halt under `yad-run`.
89
+ - **Changes that cannot be undone.** Deleting data, or a data migration with no way back.
90
+
91
+ **How to ask:**
92
+ 1. Number each item. For each one, say what must be decided, why only a human can decide it, and the
93
+ options, with your recommendation where a safe one exists.
94
+ 2. Wait for the answers, then record them where the step below says, so no later step asks again.
95
+ `yad-implement` first reads the answers `yad-spec` recorded in `spec.md`, and asks only what is
96
+ still open.
97
+ 3. If nothing is open, say "no human-only decisions or open questions" and go on.
98
+ 4. If a new one still turns up later, stop, collect any others that are open at that point, and ask
99
+ them together. In the report, say the first batch missed it.
100
+ 5. **Run by the orchestrator (`yad-run`):** a stop to ask — the first batch or a later one — is its
101
+ own halt, **waiting on human decisions**. Run `yad build step <story> --repo <repo> <step> blocked
102
+ --reason "waiting on human decisions: <the questions, short>"` (add `--task <task>` on the
103
+ implement leg). Write **no** trust entry: the step's output is not finished, and files already
104
+ drafted (such as `spec.md`) are not output to judge. Then stop. Once a person answers, the step
105
+ runs again and goes on from what is already drafted. That is a resume, not a re-run, so it is not
106
+ graded `rejected` for being run again.
107
+
108
+ <!-- end: Ask the human-only questions first -->
109
+
71
110
  ## On Activation
72
111
 
73
112
  ### Step 1 — Resolve the story and check readiness
@@ -111,18 +150,94 @@ contract here. (On a route that HAS one; the short lanes do not — see below.)
111
150
  Read Spec Kit's entry in `yad toolbox list --json --dir demo-repos/<repo>`, as **When a tool is
112
151
  missing** says. If yad cannot answer, check for `/speckit.*` slash-commands and/or
113
152
  `demo-repos/<repo>/.specify/`. Record the result for Step 6's
114
- frontmatter (`speckit: installed | not-installed`).
153
+ frontmatter (`speckit: installed | not-installed`; a light spec records `not-used` whatever is found).
115
154
 
116
155
  ### Step 5 — Run the heavy ceremony ONCE (or degrade)
117
- **Used** — from inside `demo-repos/<repo>/`, drive, in order:
118
- `/speckit.specify` → `/speckit.clarify` → `/speckit.plan` → `/speckit.analyze` →
156
+ **Start the step (#348).** From the Product, run `yad build step <story> --repo <repo> <step> in_progress`,
157
+ where `<step>` is the lane's current step when it is `spec` or `tasks` (yad-spec runs both). Run
158
+ `yad build start <story> --repo <repo>` first if the story has no lane in this repo yet. The command
159
+ records the step, and in a repo that uses Spec Kit it points `.specify/feature.json` at `specs/<story>`,
160
+ so Spec Kit never writes into the previous story's folder. Run it again on a resume: it changes nothing
161
+ that is already right. If the lane is past both steps (a re-run after a rejected spec, say), do not move
162
+ the lane: set `.specify/feature.json` to `{"feature_directory":"specs/<story>"}` by hand instead.
163
+
164
+ **Ask first (#357).** Before the long part of the ceremony, ask the batch that **Ask the human-only
165
+ questions first** above describes. Its items come from the story, `epic.md`, the contract read in
166
+ Step 3, and the first draft of `spec.md`. Record the answers in `spec.md`, under `## Clarifications`,
167
+ as `- Q: <question> → A: <answer>` lines below a `### Session <YYYY-MM-DD>` heading. This is the format
168
+ `/speckit.clarify` writes, and both paths below leave the answers there.
169
+ When the story qualifies for a **light spec** (below), put that question in the same batch.
170
+
171
+ **Light spec (#348).** A small story can have one `spec.md` instead of the full set of files. Suggest it
172
+ only when ALL of these hold:
173
+ - the route is `chore` or `spike`, or `epics/<epic>/.sdlc/change.json` says `depth: defect-fix` or
174
+ `depth: behavioral-no-surface`;
175
+ - the story's **Notes for build** says the contract surface touched is none, and Step 3 found nothing
176
+ to quote, so the spec needs no `contracts/` slice;
177
+ - nothing marks it high risk: no step in `epics/<epic>/.sdlc/state.json` carries an `auth` or
178
+ `payments` risk tag; the code repo's risk map gives no file the work will touch the level `high`
179
+ (below); and the person has not called it high risk.
180
+
181
+ **Reading the risk map for it.** The tasks do not exist yet, so judge the files the work will touch
182
+ from the draft `spec.md` and the code; if you cannot say which files, do not offer light. Read
183
+ `.sdlc/risk-map` as the default branch has it (`default_branch` in the Product's `.sdlc/repos.json`, else the
184
+ clone's `origin/HEAD`):
185
+ fetch it, then ask git whether the branch holds the file, as yad does:
186
+ `git -C demo-repos/<repo> ls-tree --full-tree origin/<default> -- .sdlc/risk-map`. Empty output (or an
187
+ entry that is not a plain file) means there is no map, so it gives no `high`; a git error (no such
188
+ branch, no fetch) is no answer. Otherwise read it with
189
+ `git -C demo-repos/<repo> show origin/<default>:.sdlc/risk-map`. `yad risk-map check` reads the
190
+ clone's working copy instead, so use its report only when the clone is on the default branch with the
191
+ map unchanged. A file's level is the one on the deepest directory listed above it (`./` covers only the
192
+ files at the root); `guessed` counts the same as `confirmed`; an `unset` line, or a file no line covers,
193
+ is not high. The map gives **no answer**, so do not offer light, when its first line that is not blank
194
+ is not the header `# yad-risk-map v1`, or a line (blank lines and `#` comments
195
+ aside) is neither `<dir>/ <high|medium|low> <guessed|confirmed>` nor `<dir>/ unset` (optionally
196
+ `<dir>/ unset guessed`), each with an optional ` # reason`, or a directory is listed twice.
197
+
198
+ Never suggest it for a story that touches the contract, and never choose it yourself: ask in the batch
199
+ ("Light spec — one `spec.md` holding the spec, the plan and the tasks?"), with the reason it qualifies,
200
+ and record the answer in `## Clarifications`. Without a clear yes, write the full spec. A light spec:
201
+ - is **only** `spec.md` and `link.md` under `demo-repos/<repo>/specs/<story>/`. `spec.md` holds the spec,
202
+ then `## Plan` (the approach, in a few lines), then `## Tasks`. No `research.md`, `data-model.md`,
203
+ `plan.md`, `tasks.md` or `contracts/`. A re-run that turns a full spec into a light one deletes
204
+ everything else in the folder (a `tasks.md` that is still there wins over the light block);
205
+ - keeps its tasks between the two marker lines `<!-- yad:tasks -->` and `<!-- /yad:tasks -->` under
206
+ `## Tasks`, once each, in the same shape as `tasks.md` (`## T01 — <goal>` and a **Files:** list).
207
+ `yad build done` and `yad-implement` read the tasks only from between the markers;
208
+ - does not run Spec Kit, whose commands need `plan.md` and `tasks.md`. Step 6 records `speckit: not-used`
209
+ and `spec-mode: light`.
210
+
211
+ **When it qualifies, ask before any Spec Kit command.** Draft `spec.md` by hand and ask the batch, the
212
+ light question in it, before running any `/speckit.*` command, so the choice is known before the path
213
+ is. On a yes, write the light spec. On a no, take one of the two paths below; on **Used**, the batch is
214
+ already asked, so copy the recorded `## Clarifications` lines out first (`/speckit.specify` replaces
215
+ `spec.md` with its template), then put them into the `spec.md` it writes instead of asking again.
216
+
217
+ The spec leg writes the whole light spec, tasks included. When the lane then reaches the `tasks` leg,
218
+ start that step as above and check that the tasks block is there and whole; write nothing else.
219
+
220
+ **Used** (and the spec is not light) — from inside `demo-repos/<repo>/`, drive, in order:
221
+ `/speckit.specify` → (ask the batch) → `/speckit.clarify` → `/speckit.plan` → `/speckit.analyze` →
119
222
  `/speckit.checklist` → `/speckit.tasks`. **Pin the feature to `<story>`** (do not accept an
120
- auto-slug). Seed `specify` from the story's acceptance criteria and the contract elements from Step 3.
223
+ auto-slug): start `/speckit.specify` with `SPECIFY_FEATURE_DIRECTORY=specs/<story>`, because without it
224
+ specify makes a numbered folder of its own. Before `/speckit.plan` and again before `/speckit.tasks`,
225
+ check that `.specify/feature.json` still names `specs/<story>`; if it does not, set it back to
226
+ `{"feature_directory":"specs/<story>"}`. Seed `specify` from the story's acceptance criteria and the contract elements from Step 3.
227
+ If Step 3 found nothing to quote, keep `contracts/` out: delete any `contracts/` folder `/speckit.specify`
228
+ or `/speckit.plan` writes, since lines that are not quoted from the lock fail contract-check.
229
+ On a resume after a question halt, keep the `spec.md` that `/speckit.specify` already wrote: do not run
230
+ it again. A hand draft made only to ask the light question is not that: run `/speckit.specify` and carry
231
+ its `## Clarifications` in. Tell them apart by `specs/<story>/checklists/requirements.md`: specify
232
+ writes it, a hand draft never does. Answer `/speckit.clarify`'s questions from the batch answers. A question it asks that the batch did not
233
+ cover is a late one: ask all such questions together, as rule 4 of the batch says.
121
234
  `/speckit.constitution` and `/speckit.implement` are **out of scope for Step A** (implement is Step B).
122
235
 
123
- **Not used (degrade)** — hand-author the identical files in Spec Kit's layout under
236
+ **Not used (degrade)** (and the spec is not light) — draft `spec.md` first, ask the batch, record the answers in it, and only then
237
+ write the rest (after a "no" to light, the batch is already asked: do not ask it again). Hand-author the identical files in Spec Kit's layout under
124
238
  `demo-repos/<repo>/specs/<story>/`: `spec.md`, `research.md`, `data-model.md`, `contracts/`,
125
- `plan.md`, `tasks.md`. The content is what a real Spec Kit run would produce, traceable to the story's
239
+ `plan.md`, `tasks.md`. Write `contracts/` only when Step 3 found surface to quote: a story with nothing to
240
+ quote has no `contracts/` folder at all (git keeps no empty folder, and an empty one quotes nothing). The content is what a real Spec Kit run would produce, traceable to the story's
126
241
  acceptance criteria and the locked contract surface. `tasks.md` MUST be numbered atomic tasks (`T01…`),
127
242
  each declaring the files it may touch, so Step B's "stay inside the declared files" rule has something
128
243
  to read. See `references/spec-handoff.md` for the exact file map and per-file degradation rules.
@@ -134,12 +249,13 @@ frontmatter linking the spec back to the product repo: `story`, `epic`, `repo`,
134
249
  place CI checks the Product out; the gates read that record first anyway), `contract-lock` (the hash **copied** from `contract-lock.json`, NOT recomputed
135
250
  in the code repo — or the literal `none` on a short-lane epic, which has no lock; never a made-up or
136
251
  empty hash, which the CI gate reads as a broken lock and fails), `speckit`
137
- (`installed | not-installed`), `generated` (date). This `link.md` plus the
252
+ (`installed | not-installed`, or `not-used` for a light spec), `spec-mode` (`light` for a light spec,
253
+ else `full`; nothing after the value on that line), `generated` (date). This `link.md` plus the
138
254
  spec folder is the authoritative record that this story's spec exists.
139
255
 
140
256
  ### Step 7 — Stop (Shape state untouched)
141
257
  Report: the spec folder path, the files written, whether Spec Kit was used, the task count from
142
- `tasks.md`, and that the next action is **Step B — `yad-implement`**. Do **not** edit the epic's
258
+ `tasks.md` (or the light spec's tasks block), whether the spec is light, and that the next action is **Step B — `yad-implement`**. Do **not** edit the epic's
143
259
  `state.json`, `approvals.json`, or `contract-lock.json`. Step A is a generation step, not a Shape gate.
144
260
 
145
261
  ### Step 8 — Record the `spec` trust signal (Phase 4b)
@@ -149,11 +265,12 @@ verdict is **anchored to the human who accepts the spec**, never self-graded:
149
265
  - the human approves the generated `specs/<story>/` untouched → `approved-unchanged`;
150
266
  - the human edits the spec/plan/tasks before accepting → `approved-with-edits` (signal
151
267
  `human_edited_spec: true`);
152
- - the spec is rejected or the ceremony re-run → `rejected`.
268
+ - the spec is rejected or the ceremony re-run → `rejected` (a resume after a question halt, #357, is
269
+ not a re-run).
153
270
  `yad-run` records a provisional entry when the spec is generated; this acceptance finalizes it (same
154
- pattern as the engineer review finalizing `implement` at `yad-engineer-review`). Write/finalize the
155
- entry in its own shard `epics/<epic>/.sdlc/trust-log/<story>-<repo>-spec-<uid>.json` (a fresh `uid` per
156
- run; readers union the folded `trust-log.json` + the loose shards). Schema:
271
+ pattern as the engineer review finalizing `implement` at `yad-engineer-review`). Finalize it with
272
+ `yad build trust <story> --repo <repo> spec --uid <uid> --verdict <v>` — the `uid` is `closed.run` on the
273
+ `spec` step in `build-state/<story>.json`. Never write the shard by hand. Schema:
157
274
  `../yad-epic/references/state-schema.md`. **Run standalone, no trust entry is written** — the
158
275
  log measures orchestrated runs. The record is advice: the `spec` dial is
159
276
  whatever the team sets with `yad dial`, and this step never changes it.
@@ -161,10 +278,14 @@ whatever the team sets with `yad dial`, and this step never changes it.
161
278
  ## Hard rules (build plan §A, Cross-cutting)
162
279
 
163
280
  - **Heavy spec once per story, not per task.** specify/clarify/plan/analyze/checklist/tasks run once
164
- per story per repo. Do not re-run the ceremony for each task.
281
+ per story per repo. Do not re-run the ceremony for each task. A **light spec** (#348) skips it, and only
282
+ when a human confirms it in the batch.
165
283
  - **Per-repo spec, shared contract.** Spec/plan/tasks live in the code repo; the contract stays
166
284
  singular in the product repo. Never widen the contract surface from here.
167
- - **Nothing auto-advances.** Step A generates files and stops; no state machine is advanced.
285
+ - **Nothing auto-advances.** Step A generates files and stops; no state machine is advanced. Step 5
286
+ only starts the lane's spec or tasks step (`in_progress`); it never closes one.
287
+ - **Human-only decisions are asked first, in one batch** (#357), before the long work — never decided
288
+ by the agent.
168
289
 
169
290
  ## Reference
170
291
  - Command list, output map, degradation rules, link.md template: `references/spec-handoff.md`.
@@ -18,10 +18,21 @@ Driven as harness slash-commands (RESEARCH-NOTES §2, Deviation 3), from **insid
18
18
  | 5 | `/speckit.checklist` | Quality checklist for the spec | checklist section under `specs/<feature-id>/` (in the degraded path, folded into `spec.md`) |
19
19
  | 6 | `/speckit.tasks` | Atomic task list | `specs/<feature-id>/tasks.md` |
20
20
 
21
+ **Ask first (#357).** Between `specify` and `clarify` — or, when the story qualifies for a light spec
22
+ (#348), on a hand draft before any Spec Kit command (SKILL.md Step 5) — the skill asks every human-only
23
+ decision and open question in one batch (SKILL.md, **Ask the human-only questions first**). The answers go into
24
+ `spec.md` under `## Clarifications`, as `- Q: <question> → A: <answer>` lines below a
25
+ `### Session <YYYY-MM-DD>` heading — the format `/speckit.clarify` writes. The degraded path writes
26
+ the same section, so `yad-implement` finds the answers in one place on both paths.
27
+
21
28
  **Excluded from Step A:** `/speckit.constitution` (project-level, one-time bootstrap) and
22
29
  `/speckit.implement` (that is Step B — the per-task build loop). Stop at `tasks`.
23
30
 
24
- **Feature-id is pinned** to the story ID (`EP-<slug>-S0N`), never Spec Kit's numbered auto-slug. If a
31
+ **Feature-id is pinned** to the story ID (`EP-<slug>-S0N`), never Spec Kit's numbered auto-slug. Two
32
+ things pin it (#348): `yad build step <story> --repo <repo> spec|tasks in_progress` writes
33
+ `{"feature_directory":"specs/<story>"}` to `.specify/feature.json`, which `/speckit.plan`, `/speckit.tasks`
34
+ and the rest read; and `/speckit.specify`, which does not read that file, is started with
35
+ `SPECIFY_FEATURE_DIRECTORY=specs/<story>`. If a
25
36
  Spec Kit version forces its own folder name, keep the run but make `link.md` (below) the crosswalk
26
37
  between the Spec-Kit slug and the permanent story ID.
27
38
 
@@ -33,12 +44,45 @@ demo-repos/<repo>/specs/<story-id>/
33
44
  research.md # decisions/unknowns resolved during clarify
34
45
  data-model.md # entities/fields THIS repo implements (quoting the shared ones from the contract)
35
46
  contracts/ # the API/event surface this repo implements (quoted from the locked contract)
36
- # OMITTED ENTIRELY on a short-lane epic — see below
47
+ # OMITTED ENTIRELY on a short-lane epic, and for a story with nothing to quote — see below
37
48
  plan.md # technical approach for this repo
38
49
  tasks.md # numbered atomic tasks (T01…), each scoped to the files it may touch
39
50
  link.md # back-pointer to the story in the product repo (Step A adds this; not a Spec Kit file)
40
51
  ```
41
52
 
53
+ ## Light spec (#348)
54
+
55
+ A small story the human confirmed as light (SKILL.md Step 5 says when to offer it) has two files only:
56
+
57
+ ```
58
+ demo-repos/<repo>/specs/<story-id>/
59
+ spec.md # the spec, then ## Plan, then ## Tasks with the marked tasks block
60
+ link.md # as below, with speckit: not-used and spec-mode: light
61
+ ```
62
+
63
+ ```markdown
64
+ # Spec — EP-<slug>-S0N
65
+
66
+ <the spec: context, the need, in scope, out of scope, acceptance criteria copied from the story>
67
+
68
+ ## Clarifications
69
+ ### Session <YYYY-MM-DD>
70
+ - Q: Light spec — one spec.md holding the spec, the plan and the tasks? → A: yes
71
+
72
+ ## Plan
73
+ <the approach for this repo in a few lines: what changes, and how it is tested>
74
+
75
+ ## Tasks
76
+ <!-- yad:tasks -->
77
+ ## T01 — <one-line goal>
78
+ **Files:** <the files it may touch>
79
+ <!-- /yad:tasks -->
80
+ ```
81
+
82
+ Each marker line appears once, alone on its line, begin before end. The tasks are read **only** from
83
+ between them (`yad build done`, `yad-implement`), so a `T01` mentioned in the spec or the plan is never
84
+ taken for a task. Spec Kit is not run for a light spec: its commands need `plan.md` and `tasks.md`.
85
+
42
86
  ## Degradation rules (when Spec Kit is not used)
43
87
 
44
88
  Author each file by hand so it is **indistinguishable in shape** from a real Spec Kit run. The content
@@ -71,6 +115,8 @@ comes from the story's acceptance criteria and the **locked contract surface**
71
115
  Markdown (`.md`). The contract-check gate then passes the slice with **no** `Contract-Change` trailer,
72
116
  because it can prove every quoted line is in the lock (issue #344). Never reword, reorder or skip a line
73
117
  inside a block: that is a surface change, and it needs the trailer.
118
+ **Leave the folder out when there is nothing to quote** — a story on a locked epic that touches none of
119
+ the surface has no `contracts/` folder (an empty one cannot be committed and quotes nothing).
74
120
  **Do NOT create this folder on a short-lane epic** (`profile: chore` or `spike`). Those routes have
75
121
  no architecture step, so there is no locked `contract.md` to quote and no lock for CI to check the
76
122
  quote against — the gate refuses a slice under a lockless epic. A short-lane story consumes the
@@ -94,7 +140,8 @@ product-repo: <path to the product repo — absolute, or relative to THIS file's
94
140
  contract-lock: sha256:<hex copied from epics/EP-<slug>/.sdlc/contract-lock.json> # or the literal
95
141
  # `none` on a short-lane epic, which has no lock. Never an empty or invented hash:
96
142
  # CI reads an unparseable value as a broken lock and fails.
97
- speckit: installed | not-installed
143
+ speckit: installed | not-installed | not-used
144
+ spec-mode: full | light
98
145
  generated: <YYYY-MM-DD>
99
146
  ---
100
147
 
@@ -18,6 +18,13 @@ reads `.sdlc/` and `reviews/` and reports.
18
18
  This skill reports on epics. For people — what each team member did since the previous working day,
19
19
  what they are working on and what is waiting — point to `yad standup` (E132) instead of rebuilding it.
20
20
 
21
+ **Start from `yad status --brief` (#349).** It prints, in about 20 lines, where the work stands: the
22
+ task branch this checkout is on and its Build step, each open epic and its next action, your open
23
+ PRs/MRs, and what is owed (debt, recorded blockers, hotfix debt, open follow-up PRs). After a context
24
+ reset — a summary, a new session — run it first, and act on what it prints rather than on what you
25
+ remember. Read the files below only for the detail it leaves out. `--json` gives the same view as data;
26
+ `--no-fetch` asks no platform.
27
+
21
28
  ### Step 1 — Resolve the epic
22
29
  If no `EP-<slug>` was given, list the epics under `{project-root}/epics/` and ask which one (or
23
30
  report all if the user asked for an overview).
@@ -10,7 +10,7 @@ Each story authored at Shape step 7 is one Markdown file under `epics/EP-<slug>/
10
10
  | `id` | `EP-<slug>-S0N` | Stable story ID. Engine-assigned, zero-padded, never renamed. |
11
11
  | `epic` | `EP-<slug>` | Parent epic ID — the unbroken link back to the epic. |
12
12
  | `owner` | name | Inherited from `epic.md` `owner` (the single source — not retyped per story). Carries the responsible owner through to Build. |
13
- | `status` | `draft` \| `in_review` \| `approved` | Story lifecycle within the stories gate. |
13
+ | `status` | `draft` \| `in-review` \| `approved`, then `in-build` \| `shipped` | Story lifecycle: the first three within the stories gate (`yad sync-status` moves them), the last two in Build (`yad build ship` sets `in-build`, `yad build done` sets `shipped`). |
14
14
  | `repos` | subset of the epic's `repos` | Which repos must implement this story. **Labels the stories review PR with the touched repos now and (Phase 3) decides where specs are scaffolded.** |
15
15
  | `code-context` | `{ repos: [<name@sha>], loaded: <date> }` | Optional. Which connected-repo code-maps anchored "Notes for build" (Shape step 7 Step 2b). The `@sha` (a repo's `syncedHead`) is recommended so freshness is recorded but may be omitted; the SKILL templates show the empty placeholder `{ repos: [], loaded: <date or none> }`. `none` / `[]` when no repos are connected. |
16
16