yadflow 4.6.0 → 4.8.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 (136) hide show
  1. package/CHANGELOG.md +259 -0
  2. package/README.md +46 -4
  3. package/bin/commands.mjs +9 -2
  4. package/bin/yad.mjs +309 -30
  5. package/cli/agent-guard.mjs +511 -0
  6. package/cli/agent-guide.mjs +83 -0
  7. package/cli/agent-rules.mjs +381 -0
  8. package/cli/argv-flags.mjs +7 -0
  9. package/cli/artifact-status.mjs +88 -20
  10. package/cli/build.mjs +1372 -0
  11. package/cli/checkpoint.mjs +2 -2
  12. package/cli/ci-check.mjs +492 -0
  13. package/cli/commit.mjs +1 -0
  14. package/cli/dial.mjs +21 -1
  15. package/cli/docs.mjs +7 -2
  16. package/cli/doctor.mjs +176 -33
  17. package/cli/epic-state.mjs +360 -12
  18. package/cli/errors.mjs +3 -0
  19. package/cli/find-product.mjs +36 -2
  20. package/cli/fold.mjs +9 -5
  21. package/cli/gate-local.mjs +9 -1
  22. package/cli/gate.mjs +364 -22
  23. package/cli/guide.mjs +549 -0
  24. package/cli/history.mjs +22 -2
  25. package/cli/hook.mjs +35 -4
  26. package/cli/index-command.mjs +2 -2
  27. package/cli/ledger.mjs +60 -0
  28. package/cli/lib.mjs +46 -0
  29. package/cli/lifecycle/defaults/2.json +124 -0
  30. package/cli/lifecycle/lifecycle.schema.json +5 -2
  31. package/cli/lifecycle.mjs +16 -3
  32. package/cli/manifest.mjs +75 -0
  33. package/cli/marked-block.mjs +48 -0
  34. package/cli/members.mjs +19 -5
  35. package/cli/migrate.mjs +17 -19
  36. package/cli/next.mjs +35 -12
  37. package/cli/openpr.mjs +81 -5
  38. package/cli/plan.mjs +326 -22
  39. package/cli/platform.mjs +21 -0
  40. package/cli/pr-list.mjs +5 -3
  41. package/cli/product-index.mjs +6 -3
  42. package/cli/product-token.mjs +186 -0
  43. package/cli/productcommit.mjs +33 -0
  44. package/cli/protection.mjs +50 -0
  45. package/cli/recommend.mjs +3 -1
  46. package/cli/reconcile.mjs +187 -26
  47. package/cli/repo-publish.mjs +2 -2
  48. package/cli/report.mjs +62 -14
  49. package/cli/run-checks.mjs +586 -0
  50. package/cli/setup.mjs +244 -25
  51. package/cli/ship-drift.mjs +49 -18
  52. package/cli/signing.mjs +377 -0
  53. package/cli/standup.mjs +1 -1
  54. package/cli/status.mjs +282 -0
  55. package/cli/test-agents-file.mjs +993 -0
  56. package/cli/test-build.mjs +1559 -0
  57. package/cli/test-ci-check.mjs +616 -0
  58. package/cli/test-guide.mjs +1267 -0
  59. package/cli/test-node.mjs +129 -0
  60. package/cli/test-run-checks.mjs +603 -0
  61. package/cli/test-setup-agent.mjs +352 -0
  62. package/cli/test-signing.mjs +524 -0
  63. package/cli/test-worktree.mjs +520 -0
  64. package/cli/thread.mjs +4 -0
  65. package/cli/tidy.mjs +2 -2
  66. package/cli/toolbox.mjs +37 -6
  67. package/cli/update-commit.mjs +313 -11
  68. package/cli/workspace.mjs +38 -10
  69. package/cli/worktree-record.mjs +53 -0
  70. package/cli/worktree.mjs +379 -0
  71. package/package.json +6 -4
  72. package/skills/sdlc/config.yaml +5 -5
  73. package/skills/sdlc/module-help.csv +2 -1
  74. package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
  75. package/skills/yad-change/SKILL.md +5 -1
  76. package/skills/yad-checks/SKILL.md +61 -12
  77. package/skills/yad-checks/references/check-gates.md +78 -14
  78. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  79. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  80. package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
  81. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  82. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  83. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  84. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  85. package/skills/yad-checks/templates/checks/package-manager.sh +42 -5
  86. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  87. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  88. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  89. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  90. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  91. package/skills/yad-checks/templates/github/yad-checks.yml +9 -9
  92. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +4 -1
  93. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +5 -5
  94. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  95. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  96. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  97. package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
  98. package/skills/yad-commit/SKILL.md +8 -5
  99. package/skills/yad-connect-repos/SKILL.md +5 -3
  100. package/skills/yad-connect-repos/references/code-context.md +2 -1
  101. package/skills/yad-connect-repos/references/repos-registry.md +2 -1
  102. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  103. package/skills/yad-docs/templates/app/package.json +2 -2
  104. package/skills/yad-docs-overview/references/pipeline-model.md +2 -2
  105. package/skills/yad-engineer-review/SKILL.md +55 -25
  106. package/skills/yad-engineer-review/references/ship-and-record.md +49 -12
  107. package/skills/yad-epic/SKILL.md +2 -1
  108. package/skills/yad-epic/references/state-schema.md +76 -17
  109. package/skills/yad-guide/SKILL.md +192 -0
  110. package/skills/yad-implement/SKILL.md +75 -13
  111. package/skills/yad-implement/references/implement-conventions.md +8 -1
  112. package/skills/yad-implement/templates/.gitmessage +3 -0
  113. package/skills/yad-open-pr/SKILL.md +21 -0
  114. package/skills/yad-pair-review/SKILL.md +14 -5
  115. package/skills/yad-pr-template/SKILL.md +6 -2
  116. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  117. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  118. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  119. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  120. package/skills/yad-product-bridge/SKILL.md +44 -12
  121. package/skills/yad-product-bridge/references/bridge.md +11 -5
  122. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
  123. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  124. package/skills/yad-reconcile/SKILL.md +9 -3
  125. package/skills/yad-report/SKILL.md +15 -0
  126. package/skills/yad-review-companion/SKILL.md +5 -3
  127. package/skills/yad-review-gate/SKILL.md +16 -8
  128. package/skills/yad-review-gate/references/gating.md +26 -1
  129. package/skills/yad-run/SKILL.md +61 -33
  130. package/skills/yad-run/references/run-loop.md +44 -22
  131. package/skills/yad-spec/SKILL.md +137 -16
  132. package/skills/yad-spec/references/spec-handoff.md +50 -3
  133. package/skills/yad-status/SKILL.md +7 -0
  134. package/skills/yad-stories/references/story-schema.md +1 -1
  135. package/skills/yad-sync-repos/SKILL.md +2 -1
  136. package/skills/yad-ui/SKILL.md +2 -2
@@ -17,7 +17,7 @@ spec → tasks → implement → checks → engineer-review(locked)
17
17
  project's setting in `.sdlc/skills.json` — for every epic, or for one route only — so the loop reads
18
18
  `yad skill list --epic <epic> --json` (that epic's route, E51) once at Step 0 and
19
19
  runs every entry of that step's `skills`, in order, when it is bound to more than one. Unbound: `spec` and `tasks` are the two legs of `yad-spec` (the heavy ceremony, then the atomic
20
- `tasks.md`), `implement` is one atomic task via `yad-implement`, and `checks` is
20
+ `tasks.md`, or the tasks block of a light `spec.md`, #348), `implement` is one atomic task via `yad-implement`, and `checks` is
21
21
  `yad-checks (action: run)`. `engineer-review` is the human gate at `yad-engineer-review` — always a
22
22
  stop, never automated, and bindable like any other step.
23
23
 
@@ -25,44 +25,61 @@ stop, never automated, and bindable like any other step.
25
25
 
26
26
  ```
27
27
  cfg = config.yaml.automation
28
- bs = build-state/<story>.json.repos[<repo>] # create the FILE from defaults if absent; if the file
29
- # exists but has no entry for <repo>, add one from the
30
- # defaults — never remove an entry you did not add
28
+ bs = build-state/<story>.json.repos[<repo>] # absent: `yad build start <story> --repo <repo>` seeds it
29
+ # from the defaults (it never touches another repo's
30
+ # entry). Never write this file by hand (#346).
31
31
  if bs.status == "skipped": # E39: the whole lane was set aside with
32
32
  STOP — report bs.record.reason # `yad skip <epic> <story> --repo <repo>`; do not drive it.
33
33
  # `yad unskip <epic> <story> --repo <repo>` puts it back.
34
34
  # Never write a single Build step as skipped or deferred.
35
- step = from or bs.currentStep
35
+ step = from or bs.currentStep # from: the lane's current step only
36
+ if task and bs.currentStep == "engineer-review" and task has no close on implement:
37
+ yad build step <story> --repo <repo> implement in_progress --task <task> # reopens implement and checks
38
+ step = "implement" # for the next task
36
39
 
37
40
  while step is a Build step (not engineer-review):
38
41
  result = run_step_skill(step) # the skill(s) `yad next --json` names for this lane
42
+ # (yad-spec moves spec/tasks to in_progress itself,
43
+ # which pins Spec Kit's feature folder — #348)
44
+
45
+ if result stopped to ask human-only questions — its first batch or a later one (#357) —
46
+ and did NOT hit its contract STOP (a contract item is the contract-touch HALT below):
47
+ # the output is not finished (a draft spec.md is not output), so no trust entry — only the halt
48
+ yad build step <story> --repo <repo> <step> blocked [--task <T>] --reason "waiting on human decisions: <the questions, short>"
49
+ checkpoint; STOP and report the questions
39
50
 
40
51
  signals = derive_signals(step, result) # see "Deriving signals"
41
52
  verdict = derive_verdict(signals) # rejected | approved-with-edits | approved-unchanged
42
- uid = fresh_short_token() # e.g. `openssl rand -hex 4` — unique per run,
43
- # never reuse; a collision would fuse two runs
44
- write trust-log/<story>-<repo>-<step>-<uid>.json # ONE shard file = ONE entry (never append to a shared file)
45
- # `automation` is recorded in the OLD vocabulary (this is a history record, and `yad migrate`
46
- # deliberately leaves it alone). Read the step's dial from EITHER spelling.
47
- = { story, repo, step, uid, automation: bs.step.automation ?? old_name_for(bs.step.advance), verdict, signals, ranBy, date }
53
+ uid = `yad build trust <story> --repo <repo> <step> --verdict <verdict> --signal <name>=<value> …
54
+ --ran-by <machine|human> {--task <T>} --json`.uid # writes ONE shard, trust-log/<story>-<repo>-<step>-<uid>.json,
55
+ # with a fresh uid and the dial in force; never by hand
48
56
 
49
57
  eff = effective_dial(step, bs, cfg) # see "Effective dial"
50
58
 
51
59
  if result is a HALT (failed / scope overrun / contract touch / ambiguous):
52
60
  # `blocked` needs its `record` (E38) — that is what separates a halted lane from one that has
53
61
  # simply not started. `reason` is the halt cause you already have in hand.
54
- bs.step.status = "blocked"
55
- bs.step.record = { reason: "<check FAIL | scope overrun | contract touch | ambiguous>",
56
- by: "<platform login, else git user.name, or null>", date: "<YYYY-MM-DD>" }
57
- persist; checkpoint; STOP and report the human action needed
62
+ yad build step <story> --repo <repo> <step> blocked [--task <T>] --reason "<check FAIL | scope overrun | contract touch | ambiguous>"
63
+ checkpoint; STOP and report the human action needed
58
64
  elif eff == "auto":
59
- bs.step.status = "done"
60
- bs.step.closed = { by: "<platform login, else git user.name, or null>", date: "<YYYY-MM-DD>", via: "auto", run: uid }
61
- advance bs.currentStep to next; persist; checkpoint; continue # Step B advance
65
+ yad build step <story> --repo <repo> <step> done --via auto --run <uid> {--task <T>} # the closing record; currentStep moves on
66
+ checkpoint; if step == checks: OPEN_PR; continue # Step B advance
62
67
  else: # "human"
63
- bs.step.status = "done"
64
- bs.step.closed = { by: "<platform login, else git user.name, or null>", date: "<YYYY-MM-DD>", via: "human", run: uid }
65
- persist; checkpoint; STOP and report "waiting for human at <next>"
68
+ yad build step <story> --repo <repo> <step> done --run <uid> {--task <T>}
69
+ checkpoint; if step == checks: OPEN_PR; STOP and report "waiting for human at <next>"
70
+
71
+ # OPEN_PR — checks closed for a task, by either dial: open its PR/MR (#356)
72
+ if `yad dial open-pr --json`.advance == "auto":
73
+ yad open-pr --via auto # from the task branch; refuses unless the checks step is closed now
74
+ # and each task the commits carry (a group, #350) has its newest
75
+ # close (--task above) with a run that passed and was not rejected;
76
+ # records `opened` on the lane, once per task
77
+ else:
78
+ STOP and ask the person to approve opening it; then `yad open-pr`
79
+
80
+ # {--task <T>}: REQUIRED on the implement and checks legs, left out on spec and tasks. <T> is the `task`
81
+ # input, else the task `yad-implement` worked on. Without it the checks close names no task, and
82
+ # `yad open-pr --via auto` refuses it.
66
83
 
67
84
  # reached engineer-review: always stop, hand to yad-engineer-review (human gate, finalizes the verdict)
68
85
  ```
@@ -78,7 +95,8 @@ Write it only when you write `done`, and never over a `closed` already on the st
78
95
  nudge; otherwise `human`. Persist build-state after every transition so a halt leaves an accurate,
79
96
  resumable record.
80
97
 
81
- `checkpoint` = run `yad checkpoint --push` from `{project-root}`. It commits the machine-written
98
+ `checkpoint` = ask the person, then run `yad checkpoint --push` from `{project-root}` (it pushes to the default
99
+ branch, which an agent asks about every time, E158). It commits the machine-written
82
100
  Build ledgers (in this loop, the loose `trust-log/` shards this run wrote + `build-state/<story>.json`;
83
101
  also the `build-log/` shards at engineer-review) — the shard dirs are what checkpoint stages, the same
84
102
  way `git gc` folds loose objects later (`yad tidy up` folds finished shards into the folded
@@ -156,6 +174,10 @@ Reverting (`--to human`) and the kill switch are always one move.
156
174
  ## What stays human, always
157
175
 
158
176
  - `engineer-review` — the merge gate. `yad-run` always stops here and hands to `yad-engineer-review`.
177
+ Opening a task's PR/MR asks a person too, unless the project gave a standing approval with
178
+ `yad dial open-pr --to auto` (#356) — the kill switch holds it at human.
179
+ The merge stays a person's; whether it happened is asked of the platform with
180
+ `yad build merged <story> --task <T> --repo <r> --ship` (#355) — never waited for in chat.
159
181
  - The Shape steps — this loop never drives them. A Shape author step's dial may be set to auto for the
160
182
  project (`yad dial <step> --to auto`), and is only recorded until the engine runs agents (E26); every
161
183
  Shape review gate is a person.
@@ -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
 
@@ -81,7 +81,8 @@ so any repo whose `HEAD` now differs from its registry `syncedHead` has a **stal
81
81
  the command ends by pointing the human at `yad repo refresh` to repack (that is a separate human
82
82
  decision; this skill never repacks or writes the registry). After the repack + AI code-map
83
83
  regeneration, `yad repo refresh --push` publishes the refreshed code-maps + registry to the Product's
84
- default branch as a `chore(product): sync code-context … [skip ci]` audit commit.
84
+ default branch as a `chore(product): sync code-context … [skip ci]` audit commit. It pushes to the default
85
+ branch, so an AI agent asks the person first, every time (E158).
85
86
 
86
87
  ## Hard rules
87
88
 
@@ -81,8 +81,8 @@ pipeline, infra work), it does not need a UI design. Two signals to watch for:
81
81
  from before shape 7, `done` with `skipped: true` beside it — the step was marked N/A. If it is
82
82
  `deferred`, the team set it aside to come back to later. Either way the `--check` above refuses it
83
83
  (`ui-design is already skipped`, or `already deferred`). **STOP**, there is nothing to author now;
84
- point the user at `yad next EP-<slug>` (the next step is `stories`). To pick a deferred UI back up,
85
- run `yad undefer EP-<slug> ui-design` first.
84
+ point the user at `yad next EP-<slug>` (the next step is `stories`). When the person asks to pick a
85
+ deferred UI back up, run `yad undefer EP-<slug> ui-design` first.
86
86
  - **Should be skipped:** if you reach this step and the epic clearly produces no screens, do **not**
87
87
  invent a hollow UI artifact. Offer to mark it N/A instead:
88
88
  `yad skip EP-<slug> ui-design --reason "<why, e.g. backend-only service>"`. That marks both the