yadflow 4.5.2 → 4.6.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.
@@ -64,6 +64,54 @@ if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
64
64
  echo "FAIL [backfill]: base ref '${BASE}' not found — fetch full history / check the base branch."
65
65
  exit 1
66
66
  fi
67
+ # What this branch changes is what MERGING it into BASE would change (#363 reviews 1, 3 and 4). A diff
68
+ # from the base's TIP (two dots) blamed the branch for what the base did after it split off. A diff from
69
+ # the merge base missed two things the real merge does: with several merge bases it reads from ONE, so a
70
+ # hand-resolved merge could undo what the other side brought in (review 1); and the merge follows a
71
+ # RENAME on the base, so an edit to a file the base moved into a protected path lands there unseen
72
+ # (review 4). `git merge-tree --write-tree` (git 2.38+) builds the merge without touching anything, and
73
+ # the diff runs from BASE to it — what GitHub's own merge checkout gives. A branch that does not merge
74
+ # cleanly fails closed: the platform cannot merge it either. An older git falls back to the merge base,
75
+ # with one merge base only and no base-side rename of a file the branch changes; otherwise it fails
76
+ # closed. No merge base at all (a shallow clone, unrelated history) fails closed too.
77
+ _mbs="$(git merge-base --all "$BASE" HEAD 2>/dev/null)" || _mbs=""
78
+ if [ -z "$_mbs" ]; then
79
+ echo "FAIL [backfill]: '${BASE}' and HEAD share no history — fetch full history (a shallow clone has no merge base) or check the base branch."
80
+ exit 1
81
+ fi
82
+ _mb_count="$(printf '%s\n' "$_mbs" | wc -l | tr -d ' ')"
83
+ # The exit code says which case this is (review 5): 0 a clean merge, 1 a conflict, 129 a git older than
84
+ # 2.38 (it does not know --write-tree), anything else git could not build it (a missing object, say).
85
+ _mt=0
86
+ _mt_out="$(git merge-tree --write-tree --no-messages "$BASE" HEAD 2>/dev/null)" || _mt=$?
87
+ DIFF_TO="${_mt_out%%$'\n'*}"
88
+ if [ "$_mt" = 0 ] && [ -n "$DIFF_TO" ] && git rev-parse --verify --quiet "${DIFF_TO}^{tree}" >/dev/null 2>&1; then
89
+ DIFF_FROM="$(git rev-parse --verify --quiet "${BASE}^{commit}")"
90
+ [ "$_mb_count" = 1 ] || echo "note [backfill]: '${BASE}' and HEAD have ${_mb_count} merge bases — the change is read as the merge into ${BASE} makes it."
91
+ elif [ "$_mt" = 1 ]; then
92
+ echo "FAIL [backfill]: this branch does not merge cleanly into ${BASE}, so what it changes there cannot be read. Merge ${BASE} into the branch, resolve the conflicts, then push again."
93
+ exit 1
94
+ elif [ "$_mt" != 129 ]; then
95
+ echo "FAIL [backfill]: git could not build the merge of this branch into ${BASE} (git merge-tree exit ${_mt}) — fetch the full history of both, then run again."
96
+ exit 1
97
+ elif [ "$_mb_count" != 1 ]; then
98
+ echo "FAIL [backfill]: '${BASE}' and HEAD have ${_mb_count} merge bases, and this git (older than 2.38) cannot build the merge into ${BASE}. Merge ${BASE} into the branch, then push again."
99
+ exit 1
100
+ else
101
+ DIFF_FROM="$_mbs"; DIFF_TO="HEAD"
102
+ # The fallback reads the branch's own diff, so an edit to a file the base has since moved would follow
103
+ # the rename into the merge unseen (review 4). Rename detection itself has limits the real merge does
104
+ # not share (review 5: `diff.renameLimit`), so it is not used: a path the base REMOVED — deleted or
105
+ # moved away — that the branch MODIFIES fails closed. Both deleting it is a clean merge, and passes.
106
+ _gone="$(git diff --no-renames --diff-filter=D --name-status -z "$_mbs" "$BASE" | tr '\n\0' '?\n' | awk 'NR % 2 == 0')" || { echo "FAIL [backfill]: git could not list what ${BASE} removed since the branch split off."; exit 1; }
107
+ _mine="$(git diff --no-renames --name-status -z "$_mbs" HEAD | tr '\n\0' '?\n' | awk 'NR % 2 == 1 { s = $0; next } s == "M" || s == "T"')" || { echo "FAIL [backfill]: git could not list what this branch changes."; exit 1; }
108
+ # A here-string, not a pipe: `grep -q` stops at the first match, and a large list written into a pipe
109
+ # it has left would end in SIGPIPE — read as "no match" under pipefail (review 5).
110
+ if [ -n "$_gone" ] && [ -n "$_mine" ] && grep -Fxq -f <(printf '%s\n' "$_mine") <<<"$_gone"; then
111
+ echo "FAIL [backfill]: ${BASE} removed or moved a file this branch changes, and this git (older than 2.38) cannot follow it into the merge. Merge ${BASE} into the branch, then push again."
112
+ exit 1
113
+ fi
114
+ fi
67
115
 
68
116
 
69
117
  # Folded as macOS and Windows fold a name (E116, as E115): `Src/` IS `src/` there, and `src/Billing/` IS
@@ -167,10 +215,10 @@ fi
167
215
  # The two are paired here, NUL by NUL, into one line — `<modes and status><TAB><path>` — and a newline
168
216
  # inside a path becomes `?`: split into lines first, one file named `a<newline>b` put every later header
169
217
  # where its path should be, and every src/<feature> change after it was never seen (review 1).
170
- changed="$(git diff --no-renames --raw -z "${BASE}..HEAD" | while IFS= read -r -d '' h && IFS= read -r -d '' p; do
218
+ changed="$(git diff --no-renames --raw -z "$DIFF_FROM" "$DIFF_TO" | while IFS= read -r -d '' h && IFS= read -r -d '' p; do
171
219
  printf '%s\t%s\n' "$h" "${p//$'\n'/?}"
172
220
  done)" || {
173
- echo "FAIL [backfill]: git could not list the changes between '${BASE}' and HEAD."
221
+ echo "FAIL [backfill]: git could not list what this branch changes in '${BASE}'."
174
222
  exit 1
175
223
  }
176
224
  # The spellings of each src/<feature> folder, on the base and at HEAD: `<top>/<feature>`, once each.
@@ -15,6 +15,19 @@ in CI on every PR/MR and must pass before merge (build plan §C). Each is a smal
15
15
  `specs/<story>/contracts/`) without a `Contract-Change: yes` trailer **and** an updated, re-locked
16
16
  contract upstream, it **FAILS and routes back to the architecture gate**. The shared surface is
17
17
  never widened from inside a code repo (Phase 2 contract representation: delimited block + SHA-256 lock).
18
+ **A quote is not a change (issue #344):** a slice whose every changed file is Markdown holding exactly
19
+ one `<!-- CONTRACT-QUOTE:BEGIN -->` … `<!-- CONTRACT-QUOTE:END -->` block (plus blank lines and, first,
20
+ the optional title `# Contract slice — <story ID>`), the block an unbroken, in-order run of the locked
21
+ `CONTRACT-SURFACE` lines, passes with **no** trailer — when the Product is reached, `link.md` pins the current lock, and the locked `contract.md`
22
+ (the owner's, for a change-epic's pointer lock) still hashes to it. Anything it cannot prove still
23
+ needs the trailer. **The change is what merging the branch into the target would change** (issue
24
+ #363; `git merge-tree`, git 2.38+), so a slice that changed on the target after the branch split off is
25
+ not this branch's, and a rename on the target cannot carry an edit into a slice unseen. A branch that
26
+ does not merge cleanly fails closed; an older git reads from the merge base and fails closed on
27
+ several merge bases or a file the target removed or moved that the branch modifies. A slice the
28
+ branch's own commits touch counts even when the merge nets it to nothing (a "Rebase and merge"
29
+ replays every commit), and its quote proof then needs the branch rebased onto the target with no
30
+ merge commits; `docs/branch-protection.md` lists the merge methods the gate models.
18
31
  Every story whose slice the diff touches is checked, not just the first — see `references/check-gates.md`.
19
32
  A claimed `Contract-Change` against an epic that has **no lock at all** fails too: an epic on a short
20
33
  lane (`chore`/`spike`) has no architecture step and never locks a surface, so it may consume the
@@ -125,13 +125,66 @@ Every gate stops on its failure except **risk-map**, which is advisory: there a
125
125
  `yad-spec` writes real files, so nothing legitimate lives there as a link. Removing a link under
126
126
  `contracts/` is a change to the surface and needs `Contract-Change: yes`; on a lockless epic it takes
127
127
  the removal hatch below. `yad doctor` warns `checks:symlink-blind` for an older copy without this check.
128
- - Computes the changed files in `<base>..HEAD`.
128
+ - Computes the changed files as **what merging the branch into the target would change** (issue #363):
129
+ `git merge-tree --write-tree <base> HEAD` (git 2.38+) builds that merge without touching anything, and
130
+ the diff runs from the target to it — what GitHub's own merge checkout gives. The quote pass reads the
131
+ slice's content, and the "whole slice removed" check its tree, from that result too. Why the merge and
132
+ not a simpler range:
133
+ - a two-dot diff compared with the target's tip, so a slice that landed on the target after the branch
134
+ split off failed a branch that never touched it;
135
+ - a diff from the merge base reads from ONE merge base when there are several (a hotfix merged into
136
+ both, stacked branches, a criss-cross merge), so a hand-resolved merge could undo what the other
137
+ side brought in (review 1);
138
+ - and it misses a **rename** on the target: the real merge follows it, so an edit to a file the target
139
+ moved into a slice (or a backfilled feature) lands there unseen (review 4).
140
+
141
+ The trailer is still read from `git log <base>..HEAD` (this branch's own commits), and so are the
142
+ slice files **the branch's own commits touch** (merge commits left out, the full history read so a
143
+ merged side's commits are not dropped): they count as touched even when the merge nets them to nothing
144
+ (review 5, the user's decision). A GitHub "Rebase and merge" replays each commit, so a commit that
145
+ mirrors the target's re-lock and a later one that undoes it would land the undo while the merge shows
146
+ no change. So when the branch's own commits touch a slice, **the quote proof also needs the branch
147
+ rebased onto the target, with no merge commits** (review 6): then every merge method lands the branch
148
+ tip, which is the merge the gate reads, and the proof is exact. Otherwise the gate says to rebase (or
149
+ add the trailer). Both paths read the `link.md` that lands, from the merge. A story "only removes" its
150
+ slice when every slice path it touches is gone from what lands.
151
+ A branch that does not merge cleanly **FAILS** closed (the platform cannot merge it either): merge the
152
+ target into it. A base that shares no history with HEAD (a shallow clone), or a merge git cannot build
153
+ (a missing object), **FAILS** closed. **Older git** (before 2.38) falls back to the merge base,
154
+ `<base>...HEAD`, and fails closed when there is more than one, or when the target **removed or moved**
155
+ a file the branch modifies (no rename detection: its limits differ from the merge's).
129
156
  - The surface is `specs/<story>/contracts` **and** everything under it: a path that IS
130
157
  `specs/<story>/contracts` (a link being removed) counts too.
131
158
  - If **nothing** under `specs/*/contracts/**` changed → **PASS** (normal implementation only *consumes*
132
159
  the contract).
133
160
  - If the surface slice changed:
134
- - Require a `Contract-Change: yes` trailer. **FAIL** (route back to the architecture gate) if absent.
161
+ - Require a `Contract-Change: yes` trailer. **FAIL** (route back to the architecture gate) if absent —
162
+ **unless every touched story's slice is an exact quote** (issue #344). A story's slice is a quote
163
+ when all of these hold, and the failure lists each one that does not:
164
+ - the story's folder is a story ID and its `link.md` is there;
165
+ - the Product is reached (the same resolution as below) and its `contract-lock.json` is readable;
166
+ - `link.md` pins that lock's hash;
167
+ - the Product's `epics/<epic>/contract.md` still hashes to the lock (the `CONTRACT-SURFACE` recipe),
168
+ so the lines are compared with the **locked** text, not a later edit. A change-epic that inherits
169
+ its architecture has a **pointer lock** (`inheritedFrom` / `ref`) and no `contract.md`: the owner's
170
+ `contract.md` is read instead, only inside the Product's `epics/`, and only while the owner's lock
171
+ still holds the copied hash. An epic that re-authored its architecture and kept the pointer fields
172
+ has its own `contract.md`, and that is read (`yad doctor` reads it too, and also warns about the
173
+ leftover fields);
174
+ - no slice file is deleted (a deletion changes the surface);
175
+ - every changed slice file is **Markdown** (`.md`; any other file under `contracts/` needs the
176
+ trailer), read from the commit by its exact name (a name holding a newline, or content holding a
177
+ zero byte, is refused), and holds **exactly one** `<!-- CONTRACT-QUOTE:BEGIN -->` …
178
+ `<!-- CONTRACT-QUOTE:END -->` block, not empty. Its non-blank lines (trailing spaces and a CR
179
+ ignored) are **one unbroken run of the locked surface's non-blank lines, in its order** — lines
180
+ checked one by one could be reordered into a different meaning (review 1), and two blocks, each a
181
+ run, could be stitched into one (review 2); to quote two parts, use two files. Outside the block the
182
+ file holds only blank lines and, as its first non-blank line, the optional title
183
+ `# Contract slice — <story ID>` (exactly that text; a leading BOM is ignored): a note there was never
184
+ read, so a new endpoint written in it passed (review 1), and a free title could say anything
185
+ (review 2). Notes go in `spec.md` or `plan.md`.
186
+ A prose slice from before this rule has no block, so it still needs the trailer until `yad-spec`
187
+ rewrites it.
135
188
  - Best-effort fidelity: when the product repo is reachable (via `link.md`'s `product-repo` path),
136
189
  require `link.md`'s pinned `contract-lock` hash to match the product repo's current
137
190
  `contract-lock.json`. A claimed change that still pins the **old** lock **FAILS** — re-run
@@ -68,7 +68,58 @@ if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
68
68
  echo "FAIL [contract-check]: base ref '${BASE}' not found — fetch full history / check the base branch."
69
69
  exit 1
70
70
  fi
71
+ # Two readings (issue #363). The TRAILER, and the slice files the branch's own commits touch, are read
72
+ # from this branch's commits: `git log BASE..HEAD` (three dots in `log` would add the base's commits
73
+ # too). The CHANGE is what merging the branch into the base makes it — the block below.
71
74
  RANGE="${BASE}..HEAD"
75
+ # What this branch changes is what MERGING it into BASE would change (#363 reviews 1, 3 and 4). A diff
76
+ # from the base's TIP (two dots) blamed the branch for what the base did after it split off. A diff from
77
+ # the merge base missed two things the real merge does: with several merge bases it reads from ONE, so a
78
+ # hand-resolved merge could undo what the other side brought in (review 1); and the merge follows a
79
+ # RENAME on the base, so an edit to a file the base moved into a protected path lands there unseen
80
+ # (review 4). `git merge-tree --write-tree` (git 2.38+) builds the merge without touching anything, and
81
+ # the diff runs from BASE to it — what GitHub's own merge checkout gives. A branch that does not merge
82
+ # cleanly fails closed: the platform cannot merge it either. An older git falls back to the merge base,
83
+ # with one merge base only and no base-side rename of a file the branch changes; otherwise it fails
84
+ # closed. No merge base at all (a shallow clone, unrelated history) fails closed too.
85
+ _mbs="$(git merge-base --all "$BASE" HEAD 2>/dev/null)" || _mbs=""
86
+ if [ -z "$_mbs" ]; then
87
+ echo "FAIL [contract-check]: '${BASE}' and HEAD share no history — fetch full history (a shallow clone has no merge base) or check the base branch."
88
+ exit 1
89
+ fi
90
+ _mb_count="$(printf '%s\n' "$_mbs" | wc -l | tr -d ' ')"
91
+ # The exit code says which case this is (review 5): 0 a clean merge, 1 a conflict, 129 a git older than
92
+ # 2.38 (it does not know --write-tree), anything else git could not build it (a missing object, say).
93
+ _mt=0
94
+ _mt_out="$(git merge-tree --write-tree --no-messages "$BASE" HEAD 2>/dev/null)" || _mt=$?
95
+ DIFF_TO="${_mt_out%%$'\n'*}"
96
+ if [ "$_mt" = 0 ] && [ -n "$DIFF_TO" ] && git rev-parse --verify --quiet "${DIFF_TO}^{tree}" >/dev/null 2>&1; then
97
+ DIFF_FROM="$(git rev-parse --verify --quiet "${BASE}^{commit}")"
98
+ [ "$_mb_count" = 1 ] || echo "note [contract-check]: '${BASE}' and HEAD have ${_mb_count} merge bases — the change is read as the merge into ${BASE} makes it."
99
+ elif [ "$_mt" = 1 ]; then
100
+ echo "FAIL [contract-check]: this branch does not merge cleanly into ${BASE}, so what it changes there cannot be read. Merge ${BASE} into the branch, resolve the conflicts, then push again."
101
+ exit 1
102
+ elif [ "$_mt" != 129 ]; then
103
+ echo "FAIL [contract-check]: git could not build the merge of this branch into ${BASE} (git merge-tree exit ${_mt}) — fetch the full history of both, then run again."
104
+ exit 1
105
+ elif [ "$_mb_count" != 1 ]; then
106
+ echo "FAIL [contract-check]: '${BASE}' and HEAD have ${_mb_count} merge bases, and this git (older than 2.38) cannot build the merge into ${BASE}. Merge ${BASE} into the branch, then push again."
107
+ exit 1
108
+ else
109
+ DIFF_FROM="$_mbs"; DIFF_TO="HEAD"
110
+ # The fallback reads the branch's own diff, so an edit to a file the base has since moved would follow
111
+ # the rename into the merge unseen (review 4). Rename detection itself has limits the real merge does
112
+ # not share (review 5: `diff.renameLimit`), so it is not used: a path the base REMOVED — deleted or
113
+ # moved away — that the branch MODIFIES fails closed. Both deleting it is a clean merge, and passes.
114
+ _gone="$(git diff --no-renames --diff-filter=D --name-status -z "$_mbs" "$BASE" | tr '\n\0' '?\n' | awk 'NR % 2 == 0')" || { echo "FAIL [contract-check]: git could not list what ${BASE} removed since the branch split off."; exit 1; }
115
+ _mine="$(git diff --no-renames --name-status -z "$_mbs" HEAD | tr '\n\0' '?\n' | awk 'NR % 2 == 1 { s = $0; next } s == "M" || s == "T"')" || { echo "FAIL [contract-check]: git could not list what this branch changes."; exit 1; }
116
+ # A here-string, not a pipe: `grep -q` stops at the first match, and a large list written into a pipe
117
+ # it has left would end in SIGPIPE — read as "no match" under pipefail (review 5).
118
+ if [ -n "$_gone" ] && [ -n "$_mine" ] && grep -Fxq -f <(printf '%s\n' "$_mine") <<<"$_gone"; then
119
+ echo "FAIL [contract-check]: ${BASE} removed or moved a file this branch changes, and this git (older than 2.38) cannot follow it into the merge. Merge ${BASE} into the branch, then push again."
120
+ exit 1
121
+ fi
122
+ fi
72
123
 
73
124
  # No symlink and no submodule anywhere under specs/ (E115). The gate reads PATHS: a link lets the
74
125
  # content live somewhere the paths below never name. A symlink at `specs`, `specs/<story>` or
@@ -144,25 +195,22 @@ fi
144
195
  # slice change and failed the PR over a file that does not exist.
145
196
  # Both lists (this one and `deleted` below) are built the SAME way: the no-lock escape hatch compares
146
197
  # them line for line.
147
- changed="$(git diff --no-renames --name-only -z "$RANGE" | tr '\n\0' '?\n')"
148
- surface="$(printf '%s\n' "$changed" | grep -E '^specs/[^/]+/contracts(/|$)' || true)"
198
+ changed="$(git diff --no-renames --name-only -z "$DIFF_FROM" "$DIFF_TO" | tr '\n\0' '?\n')"
199
+ # The slice files the branch's OWN commits touch count too, even when the merge nets them to nothing
200
+ # (review 5, the user's decision): a "Rebase and merge" replays each commit, so a commit that mirrors the
201
+ # base's re-lock and a later one that undoes it lands the undo, while the merge shows no change. The
202
+ # base's commits are not in this range, so a slice that changed only there is still not this branch's.
203
+ # `--full-history` (review 6): `git log -- <path>` otherwise simplifies history and drops a merged side's
204
+ # commits whose result matches the other parent — a slice edit there would replay in a rebase unseen.
205
+ own="$(git log --full-history --no-merges --no-renames --format= --name-only -z "$RANGE" -- specs | tr '\n\0' '?\n')"
206
+ surface="$(printf '%s\n%s\n' "$changed" "$own" | grep -E '^specs/[^/]+/contracts(/|$)' | sort -u || true)"
149
207
 
150
- # Slice paths this diff DELETES. `--name-only` above lists a deleted file exactly like a changed one,
151
- # which is right for the trailer rule — removing an agreed endpoint IS a surface change — but it
152
- # creates a dead end for the one epic that should never have had a slice in the first place.
153
- #
154
- # A short-lane epic has no lock and never will (E40). Once a `specs/<story>/contracts/` file exists
155
- # under one, the unflagged rule below fails the commit, the no-lock rule further down fails the
156
- # flagged one, and the cleanup commit that DELETES the file fails too — so there is no diff that
157
- # passes, including the correct one. An escape hatch is not optional there.
158
- #
159
- # Deleting your own copy of a surface that nothing upstream has locked cannot widen it: with no lock
160
- # there is no agreed shape for the deletion to contradict. So a delete-only diff is allowed through
161
- # the no-lock branch (and only that branch — where a lock EXISTS, a deletion is still a real surface
162
- # change and every rule below applies to it unchanged).
163
- # --no-renames matters here too: a slice MOVED out of contracts/ is a delete of the old path, and
164
- # without it git reports an `R`, which --diff-filter=D never matches — the hatch would refuse the move.
165
- deleted="$(git diff --no-renames --diff-filter=D --name-only -z "$RANGE" | tr '\n\0' '?\n' | grep -E '^specs/[^/]+/contracts(/|$)' || true)"
208
+ # A story that only REMOVES its slice is told apart below by what LANDS (review 6): every touched slice
209
+ # path is gone from the merge. A short-lane epic has no lock and never will (E40); once a
210
+ # `specs/<story>/contracts/` file exists under one, the unflagged rule fails the commit and the no-lock
211
+ # rule fails the flagged one — so deleting the file has to pass, or there is no way out. Deleting your
212
+ # own copy of a surface nothing upstream has locked cannot widen it. Where a lock EXISTS, a deletion is
213
+ # still a real surface change, and every rule below applies to it unchanged.
166
214
 
167
215
  if [ -z "$surface" ]; then
168
216
  echo "PASS [contract-check]: diff does not touch the contract surface (specs/*/contracts and everything under it)."
@@ -173,15 +221,11 @@ echo "note [contract-check]: diff touches the contract surface:"
173
221
  printf '%s\n' "$surface" | sed 's/^/ /'
174
222
 
175
223
  cc="$(git log "$RANGE" --format='%(trailers:key=Contract-Change,valueonly)' | sed '/^$/d' | tr 'A-Z' 'a-z')"
176
- if ! printf '%s\n' "$cc" | grep -qx 'yes'; then
177
- echo "FAIL [contract-check]: contract surface changed without a 'Contract-Change: yes' trailer."
178
- echo " -> Route back to the architecture gate: update + re-lock contract.md in the product repo,"
179
- echo " or, if this epic is on a short lane (chore/spike) and has no architecture gate, move the"
180
- echo " surface change to a new epic on the classic route,"
181
- echo " re-run yad-spec, then implement with Contract-Change: yes. The surface is never widened"
182
- echo " from inside a code repo."
183
- exit 1
184
- fi
224
+ # No trailer is not yet a FAIL (issue #344): a slice that only QUOTES the locked contract word for word
225
+ # changes nothing, and demanding `Contract-Change: yes` for it made the trailer mean nothing. The quote
226
+ # pass below (after the helpers it needs) decides; anything it cannot prove is the FAIL it always was.
227
+ no_trailer=""
228
+ printf '%s\n' "$cc" | grep -qx 'yes' || no_trailer=1
185
229
 
186
230
  # --- shared link.md resolution (byte-identical in contract-check / lineage-check / epic-open /
187
231
  # --- reconcile-debt-check; the gates are deliberately standalone, so it is duplicated, not sourced) ---
@@ -559,6 +603,191 @@ resolve_product() {
559
603
  esac
560
604
  }
561
605
 
606
+ # The `"hash": "sha256:<hex>"` of a contract-lock.json, hex only. Newline-tolerant, first match: the key
607
+ # and its value may legally sit on separate lines. Empty when there is none (`|| true`: under `pipefail`
608
+ # a no-match grep would fail the pipeline).
609
+ lock_hash() { tr '\n' ' ' < "$1" | grep -oE '"hash"[[:space:]]*:[[:space:]]*"sha256:[0-9a-f]+"' | head -1 | sed -E 's/.*sha256:([0-9a-f]+)"$/\1/' || true; }
610
+ # One string value of a lock file ($2 = its key), the same newline-tolerant way. Empty when absent.
611
+ lock_str() { tr '\n' ' ' < "$1" | grep -oE "\"$2\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)"$/\1/' || true; }
612
+
613
+ # The lines of a contract.md's CONTRACT-SURFACE block, as yadflow hashes them (contractSurfaceHash in
614
+ # cli/epic-state.mjs): a CR before the newline dropped, every line once with its newline.
615
+ surface_lines() { awk '{ sub(/\r$/, "") } /CONTRACT-SURFACE:BEGIN/ { f = 1; next } /CONTRACT-SURFACE:END/ { f = 0; next } f' "$1"; }
616
+ sha256_hex() {
617
+ if command -v sha256sum >/dev/null 2>&1; then sha256sum | cut -d' ' -f1
618
+ elif command -v shasum >/dev/null 2>&1; then shasum -a 256 | cut -d' ' -f1
619
+ else return 1; fi
620
+ }
621
+ # The physical path of a folder, or nothing when it cannot be entered.
622
+ phys_dir() { (cd "$1" 2>/dev/null && pwd -P) || true; }
623
+
624
+ # Issue #344: is story $1's changed slice an exact quote of its locked contract? Says why not, one line
625
+ # per reason, and returns 1. Sets `current` (the lock's hash) for the caller's note.
626
+ #
627
+ # A slice file is a quote when it is Markdown, holds exactly ONE `<!-- CONTRACT-QUOTE:BEGIN -->` …
628
+ # `<!-- CONTRACT-QUOTE:END -->` block whose non-blank lines are one UNBROKEN, IN-ORDER run of the locked
629
+ # surface's non-blank lines, and holds nothing else but blank lines and, as its first non-blank line, the
630
+ # optional title `# Contract slice — <story ID>` (review 2: two blocks, each a run, could be stitched
631
+ # into a meaning the lock never had, and a free title could say anything; review 1: notes outside a
632
+ # block were never read, so a new endpoint written there passed; and
633
+ # lines checked one by one could be reordered into a different meaning). Its content is read from the
634
+ # commit by its exact name (review 1: a newline in a name, written as `?` in the list, opened a
635
+ # different file on disk), so a name holding a newline is refused.
636
+ quote_story() {
637
+ _qs="$1"; _qbad=0; current=""
638
+ if ! story_ok "$_qs"; then
639
+ echo " ${_qs}: specs/${_qs}/contracts is not under a story ID — it quotes no lock."; return 1
640
+ fi
641
+ _qp="specs/${_qs}/contracts" # a story ID holds no pattern character, so this pathspec is exact
642
+ yad_tmp
643
+ git diff --no-renames --diff-filter=D --name-only -z "$DIFF_FROM" "$DIFF_TO" -- "$_qp" > "$_yad_tmp/q-gone" || { echo " ${_qs}: git could not list the slice's deletions."; return 1; }
644
+ { git diff --no-renames --diff-filter=d --name-only -z "$DIFF_FROM" "$DIFF_TO" -- "$_qp" && git log --full-history --no-merges --no-renames --format= --name-only -z "$RANGE" -- "$_qp"; } | sort -z -u > "$_yad_tmp/q-files" || { echo " ${_qs}: git could not list the slice's changes."; return 1; }
645
+ # Never a PASS by an empty list: the surface named this story, so its slice has changed files.
646
+ if [ ! -s "$_yad_tmp/q-files" ] && [ ! -s "$_yad_tmp/q-gone" ]; then
647
+ echo " ${_qs}: git listed no changed slice file for this story — the quote cannot be checked."; return 1
648
+ fi
649
+ if [ -s "$_yad_tmp/q-gone" ]; then
650
+ tr '\n\0' '?\n' < "$_yad_tmp/q-gone" | while IFS= read -r _f; do echo " ${_f}: this removes slice file(s) — a deletion changes the surface."; done
651
+ return 1
652
+ fi
653
+ # When the branch's own commits touch the slice, a "Rebase and merge" replays them one by one, and what
654
+ # that lands is not the merge this gate reads (reviews 5 and 6: mirror-then-undo commits, and commits
655
+ # hidden behind a merge). The quote proof is exact only when the branch already holds the base and has
656
+ # no merge commits: then every merge method lands the branch tip, which IS the merge read below.
657
+ # Otherwise the trailer is needed — or a rebase onto the base.
658
+ if [ -n "$(git log --full-history --no-merges --format=%H "$RANGE" -- "$_qp")" ]; then
659
+ if ! git merge-base --is-ancestor "$BASE" HEAD 2>/dev/null || [ -n "$(git rev-list --merges "$RANGE")" ]; then
660
+ echo " ${_qs}: this branch's own commits change the slice, and it is not rebased onto ${BASE} (or holds merge commits) — a quote can be proven only on a branch rebased onto ${BASE}. Rebase it, then push again."
661
+ return 1
662
+ fi
663
+ fi
664
+ _ql="specs/${_qs}/link.md"
665
+ # The link.md that LANDS (review 5): the base may have re-pinned it since the branch split off.
666
+ if ! git cat-file blob "${DIFF_TO}:${_ql}" > "$_yad_tmp/q-link.md" 2>/dev/null; then
667
+ echo " ${_qs}: ${_ql} is not there, so the slice is tied to no lock — re-run yad-spec."; return 1
668
+ fi
669
+ _qpin="$(printf '%s' "$(link_val contract-lock "$_yad_tmp/q-link.md")" | sed -E 's/^sha256:([0-9a-f]+).*$/\1/')"
670
+ product_for "$_qs"
671
+ if [ -n "$prod_note" ]; then printf '%s\n' "$prod_note" | sed 's/^/note [contract-check]: /'; fi
672
+ if [ -n "$prod_fail" ]; then echo " ${_qs}: ${prod_fail}"; return 1; fi
673
+ _qepic="$(story_epic "$_qs")"
674
+ _qlock=""
675
+ [ -n "$prod" ] && _qlock="${prod}/epics/${_qepic}/.sdlc/contract-lock.json"
676
+ if [ -z "$_qlock" ] || [ ! -f "$_qlock" ]; then
677
+ echo " ${_qs}: cannot check ${_qs}'s slice against its lock — the Product's lock is not reachable at ${_qlock:-<no product-repo in ${_ql}>}."
678
+ return 1
679
+ fi
680
+ current="$(lock_hash "$_qlock")" || current=""
681
+ if [ -z "$current" ]; then echo " ${_qs}: ${_qlock} has no readable \"hash\": \"sha256:…\" value."; return 1; fi
682
+ if [ -z "$_qpin" ]; then
683
+ echo " ${_qs}: ${_ql} names no contract-lock — re-run yad-spec, which copies it from the Product."; return 1
684
+ fi
685
+ if [ "$_qpin" != "$current" ]; then
686
+ echo " ${_qs}: ${_ql} pins ${_qpin:0:12}…, not the current lock ${current:0:12}… — re-run yad-spec."
687
+ return 1
688
+ fi
689
+ # Where the locked text lives. A change-epic that inherits its architecture carries a POINTER lock
690
+ # (`inheritedFrom` / `ref`, yad-change) and no contract.md of its own: the surface is the owner's. Read
691
+ # it there, as `yad doctor` does — only inside this Product's epics/, and only when the owner's lock
692
+ # still holds the hash this one copied. An epic WITH its own contract.md re-authored its architecture
693
+ # and left the pointer fields behind: its own surface is read (review 2). `yad doctor` reads it too, and
694
+ # also still checks the pointer and warns about the leftover fields; the gate needs only the surface
695
+ # the quote is compared with, so it does not.
696
+ _qc="${prod}/epics/${_qepic}/contract.md"
697
+ _qref="$(lock_str "$_qlock" ref)"
698
+ _qfrom="$(lock_str "$_qlock" inheritedFrom)"
699
+ if [ ! -f "$_qc" ] && { [ -n "$_qref" ] || [ -n "$_qfrom" ]; }; then
700
+ [ -n "$_qref" ] || _qref="../../${_qfrom}/.sdlc/contract-lock.json"
701
+ _qepics="$(phys_dir "${prod}/epics")"
702
+ case "$_qref" in /*) _qrefp="$_qref" ;; *) _qrefp="${prod}/epics/${_qepic}/.sdlc/${_qref}" ;; esac
703
+ _qowner_sdlc="$(phys_dir "$(dirname "$_qrefp")")"
704
+ [ -n "$_qepics" ] || _qowner_sdlc=""
705
+ case "$_qowner_sdlc" in
706
+ "$_qepics"/*/.sdlc) ;;
707
+ *) echo " ${_qs}: ${_qepic}'s pointer lock names '${_qref}', which is not another epic's lock in this Product."; return 1 ;;
708
+ esac
709
+ _qowner_lock="${_qowner_sdlc}/$(basename "$_qref")"
710
+ if [ "$(basename "$_qref")" != "contract-lock.json" ] || [ ! -f "$_qowner_lock" ]; then
711
+ echo " ${_qs}: ${_qepic}'s pointer lock names '${_qref}', and there is no lock there."; return 1
712
+ fi
713
+ if [ "$(lock_hash "$_qowner_lock")" != "$current" ]; then
714
+ echo " ${_qs}: ${_qepic}'s pointer lock copies ${current:0:12}…, but its owner now locks another surface — re-copy the owner's hash (yad-change)."; return 1
715
+ fi
716
+ _qc="$(dirname "$_qowner_sdlc")/contract.md"
717
+ fi
718
+ if [ ! -f "$_qc" ]; then echo " ${_qs}: ${_qc} is not there — nothing to quote from."; return 1; fi
719
+ surface_lines "$_qc" > "$_yad_tmp/surface"
720
+ _qh="$(sha256_hex < "$_yad_tmp/surface")" || _qh=""
721
+ if [ -z "$_qh" ]; then echo " ${_qs}: no sha256sum or shasum on this machine — the lock cannot be checked."; return 1; fi
722
+ if [ "$_qh" != "$current" ]; then
723
+ echo " ${_qs}: the Product's contract.md no longer matches its lock (${_qh:0:12}… vs ${current:0:12}…) — re-lock it upstream (yad-architecture Step 5)."
724
+ return 1
725
+ fi
726
+ while IFS= read -r -d '' _f; do
727
+ [ -n "$_f" ] || continue # never a name; an empty record is skipped rather than read
728
+ case "$_f" in
729
+ *$'\n'*) echo " ${_f//$'\n'/?}: a slice file name holding a newline is not read — rename it."; _qbad=1; continue ;;
730
+ esac
731
+ case "$_f" in
732
+ *.md) ;;
733
+ *) echo " ${_f}: only a Markdown slice can pass as a quote; any other file under contracts/ needs the trailer."; _qbad=1; continue ;;
734
+ esac
735
+ # The content as it lands (the merge into the base; with the rule above, also the branch tip), by its
736
+ # exact name — never a file on disk that a folded name might point at.
737
+ if ! git cat-file blob "${DIFF_TO}:${_f}" > "$_yad_tmp/q-file" 2>/dev/null; then
738
+ echo " ${_f}: the branch's own commits touch it, but it is not in what lands (added and removed again?) — that needs the trailer."; _qbad=1; continue
739
+ fi
740
+ # A zero byte ends a line for some awks (macOS), so text after it was never compared (review 2).
741
+ if ! tr -d '\000' < "$_yad_tmp/q-file" | cmp -s - "$_yad_tmp/q-file"; then
742
+ echo " ${_f}: holds a zero byte — a slice is text; it is not read."; _qbad=1; continue
743
+ fi
744
+ _qv="$(awk -v title="# Contract slice — ${_qs}" -v bom="$(printf '\357\273\277')" '
745
+ function norm(x) { sub(/\r$/, "", x); sub(/[ \t]+$/, "", x); return x }
746
+ FILENAME == ARGV[1] { $0 = norm($0); if ($0 != "") { surf = surf "\n" $0; s[$0] = 1 } next }
747
+ { if (FNR == 1 && index($0, bom) == 1) $0 = substr($0, length(bom) + 1); $0 = norm($0) }
748
+ $0 == "<!-- CONTRACT-QUOTE:BEGIN -->" { if (inb) bad = "nested"; inb = 1; blocks++; seen = 1; q = ""; qfirst = ""; next }
749
+ $0 == "<!-- CONTRACT-QUOTE:END -->" {
750
+ if (!inb) { bad = "order"; next }
751
+ inb = 0
752
+ if (q == "") { if (res == "") res = "empty"; next }
753
+ if (res == "" && index(surf "\n", q "\n") == 0) res = "run " qfirst
754
+ next
755
+ }
756
+ inb {
757
+ if ($0 == "") next
758
+ if (!($0 in s) && miss == "") miss = $0
759
+ if (qfirst == "") qfirst = $0
760
+ q = q "\n" $0
761
+ next
762
+ }
763
+ $0 == "" { next }
764
+ $0 == title && !seen { seen = 1; next }
765
+ { seen = 1 }
766
+ outside == "" { outside = $0 }
767
+ END {
768
+ if (bad != "" || inb) { print "count"; exit }
769
+ if (blocks == 0) { print "none"; exit }
770
+ if (blocks > 1) { print "many"; exit }
771
+ if (outside != "") { print "outside " outside; exit }
772
+ if (miss != "") { print "miss " miss; exit }
773
+ if (res != "") { print res; exit }
774
+ print "ok"
775
+ }' "$_yad_tmp/surface" - < "$_yad_tmp/q-file")" || _qv="unreadable"
776
+ case "$_qv" in
777
+ ok) ;;
778
+ none) echo " ${_f}: has no CONTRACT-QUOTE block, so it cannot be told from a change."; _qbad=1 ;;
779
+ count) echo " ${_f}: every CONTRACT-QUOTE block must be closed, BEGIN before END, none inside another."; _qbad=1 ;;
780
+ many) echo " ${_f}: holds more than one CONTRACT-QUOTE block — one block per file; quote another part of the surface in another file."; _qbad=1 ;;
781
+ empty) echo " ${_f}: a CONTRACT-QUOTE block quotes nothing."; _qbad=1 ;;
782
+ outside*) echo " ${_f}: this line sits outside the CONTRACT-QUOTE block: ${_qv#outside?} — only blank lines and, first, the title '# Contract slice — ${_qs}' may; notes go in spec.md or plan.md."; _qbad=1 ;;
783
+ miss*) echo " ${_f}: this line is not in the locked surface: ${_qv#miss?}"; _qbad=1 ;;
784
+ run*) echo " ${_f}: the block starting '${_qv#run?}' is not one unbroken run of the locked surface, in its order — quote whole consecutive lines."; _qbad=1 ;;
785
+ *) echo " ${_f}: could not be read."; _qbad=1 ;;
786
+ esac
787
+ done < "$_yad_tmp/q-files"
788
+ return "$_qbad"
789
+ }
790
+
562
791
  # Fidelity check (best-effort): when the product repo is reachable, the story's link.md must pin the
563
792
  # CURRENT product lock — proof the contract was actually updated/re-locked upstream, not just flagged.
564
793
  #
@@ -570,21 +799,70 @@ resolve_product() {
570
799
  # (the same rule spec-link applies per commit).
571
800
  stories="$(printf '%s\n' "$surface" | sed -E 's#^specs/([^/]+)/contracts(/.*)?$#\1#' | sort -u)"
572
801
  rc=0
802
+
803
+ # --- issue #344: with no trailer, pass only a slice that is an exact quote of its locked contract ---
804
+ # yad-spec writes the lines it copies from the locked CONTRACT-SURFACE block between
805
+ # `<!-- CONTRACT-QUOTE:BEGIN -->` and `<!-- CONTRACT-QUOTE:END -->`. What makes a slice a quote — and
806
+ # every rule reviews 1 and 2 added to keep a changed surface from passing as one — is said once, above
807
+ # `quote_story`. Anything it cannot prove is the trailer's FAIL, as before #344.
808
+ if [ -n "$no_trailer" ]; then
809
+ quote_ok=1
810
+ while IFS= read -r story; do
811
+ [ -z "$story" ] && continue
812
+ if quote_story "$story"; then
813
+ echo "note [contract-check]: ${story}'s slice is an exact quote of the locked contract (${current:0:12}…)."
814
+ else
815
+ quote_ok=""
816
+ fi
817
+ done <<QSTORIES
818
+ $stories
819
+ QSTORIES
820
+ if [ -n "$quote_ok" ]; then
821
+ echo "PASS [contract-check]: every changed slice is an exact quote of its locked contract — no Contract-Change trailer needed."
822
+ exit 0
823
+ fi
824
+ echo "FAIL [contract-check]: contract surface changed without a 'Contract-Change: yes' trailer."
825
+ echo " -> If the slice only QUOTES the locked contract: one Markdown file per unbroken run of the surface,"
826
+ echo " holding one <!-- CONTRACT-QUOTE:BEGIN --> … <!-- CONTRACT-QUOTE:END --> block and nothing else but"
827
+ echo " blank lines and the title '# Contract slice — <story ID>' (re-run yad-spec); fix what is listed above."
828
+ echo " -> If it changes the surface: Route back to the architecture gate — update + re-lock contract.md"
829
+ echo " in the product repo, or, if this epic is on a short lane (chore/spike) and has no architecture"
830
+ echo " gate, move the surface change to a new epic on the classic route,"
831
+ echo " re-run yad-spec, then implement with Contract-Change: yes. The surface is never widened"
832
+ echo " from inside a code repo."
833
+ exit 1
834
+ fi
573
835
  while IFS= read -r story; do
574
836
  [ -z "$story" ] && continue
575
837
  # This story's own changed and deleted slice paths, matched as text (a folder that is not a story ID
576
838
  # may hold characters a pattern would read; the prefix goes in through the environment, because
577
- # `awk -v` turns a `\b` in a folder name into a backspace). A story whose every changed slice file is
578
- # DELETED only removes (only_removes); one whose slice is also GONE at HEAD (slice_gone) is a whole
839
+ # `awk -v` turns a `\b` in a folder name into a backspace). A story whose every touched slice file is
840
+ # gone from what lands only removes (only_removes); one whose slice folder is also GONE (slice_gone) is a whole
579
841
  # clean-up, the only kind that needs no link.md — deleting link.md with PART of a slice used to drop
580
842
  # a stale pin while the rest of the slice stayed (E117 review 3).
581
843
  story_surface="$(printf '%s\n' "$surface" | p="specs/${story}/contracts" awk 'BEGIN { p = ENVIRON["p"] } index($0, p) == 1 && (length($0) == length(p) || substr($0, length(p) + 1, 1) == "/")')"
582
- story_deleted="$(printf '%s\n' "$deleted" | p="specs/${story}/contracts" awk 'BEGIN { p = ENVIRON["p"] } index($0, p) == 1 && (length($0) == length(p) || substr($0, length(p) + 1, 1) == "/")')"
844
+ # Only removes: every slice path the story touches is gone from what lands (review 6: a file added and
845
+ # removed again on the branch is in the surface but in no delete list). A folded name (`?`) cannot be
846
+ # looked up exactly, so it never counts as gone.
583
847
  only_removes=""
584
- [ -n "$story_surface" ] && [ "$story_surface" = "$story_deleted" ] && only_removes=1
848
+ if [ -n "$story_surface" ]; then
849
+ only_removes=1
850
+ while IFS= read -r _p; do
851
+ case "$_p" in *'?'*) only_removes=""; break ;; esac
852
+ if git cat-file -e "${DIFF_TO}:${_p}" 2>/dev/null; then only_removes=""; break; fi
853
+ done <<STORYSURF
854
+ $story_surface
855
+ STORYSURF
856
+ fi
585
857
  slice_gone=""
586
- if [ -n "$only_removes" ] && ! git cat-file -e "HEAD:specs/${story}/contracts" 2>/dev/null; then slice_gone=1; fi
858
+ # Gone from what LANDS (the merge into the base, review 4): a file the base adds beside the deletion
859
+ # would otherwise be a slice left with no link.md.
860
+ if [ -n "$only_removes" ] && ! git cat-file -e "${DIFF_TO}:specs/${story}/contracts" 2>/dev/null; then slice_gone=1; fi
587
861
  link="specs/${story}/link.md"
862
+ # The link.md that LANDS (review 6, the twin of the quote pass): the base may have re-pinned or removed it.
863
+ yad_tmp
864
+ landed_link=""
865
+ if git cat-file blob "${DIFF_TO}:${link}" > "$_yad_tmp/t-link.md" 2>/dev/null; then landed_link="$_yad_tmp/t-link.md"; fi
588
866
  if ! story_ok "$story"; then
589
867
  if [ -n "$only_removes" ]; then
590
868
  echo "note [contract-check]: specs/${story}/contracts is not under a story ID, and this only removes it — allowed."
@@ -595,7 +873,7 @@ while IFS= read -r story; do
595
873
  rc=1
596
874
  continue
597
875
  fi
598
- if [ ! -f "$link" ]; then
876
+ if [ -z "$landed_link" ]; then
599
877
  # Removing a story's whole slice with its link.md is a clean-up, as before. Adding or changing a
600
878
  # slice without its link.md is not (E117 review 2): yad-spec writes the two together, and a PR could
601
879
  # delete link.md to drop a stale pin, or add a slice for an epic that exists nowhere. Nor is removing
@@ -609,7 +887,7 @@ while IFS= read -r story; do
609
887
  rc=1
610
888
  continue
611
889
  fi
612
- pinned="$(printf '%s' "$(link_val contract-lock "$link")" | sed -E 's/^sha256:([0-9a-f]+).*$/\1/')"
890
+ pinned="$(printf '%s' "$(link_val contract-lock "$landed_link")" | sed -E 's/^sha256:([0-9a-f]+).*$/\1/')"
613
891
  epic="$(story_epic "$story")" # story EP-<slug>-S0N -> epic EP-<slug>
614
892
  product_for "$story"
615
893
  if [ -n "$prod_note" ]; then printf '%s\n' "$prod_note" | sed 's/^/note [contract-check]: /'; fi
@@ -628,7 +906,7 @@ while IFS= read -r story; do
628
906
  # unparseable lock is a FAIL below — so a formatting choice must not become a gate failure.
629
907
  # `|| current=""` is load-bearing: under `pipefail` a no-match grep fails the whole pipeline, which
630
908
  # under `set -e` would abort the gate instead of reaching the unparseable-lock FAIL below.
631
- current="$(tr '\n' ' ' < "$lock" | grep -oE '"hash"[[:space:]]*:[[:space:]]*"sha256:[0-9a-f]+"' | head -1 | sed -E 's/.*sha256:([0-9a-f]+)"$/\1/')" || current=""
909
+ current="$(lock_hash "$lock")" || current=""
632
910
  # A lock we can READ but cannot PARSE proves nothing, and an empty `current` used to short-circuit
633
911
  # the comparison below straight into the "hash matches" note — the gate affirmatively reporting a
634
912
  # match it never made. Fail closed instead: a truncated, half-written or schema-changed lock is a
@@ -95,13 +95,15 @@ Each `steps[]` entry:
95
95
 
96
96
  ### The step catalogue
97
97
 
98
- Every one of those ids is defined in **one place in the code** — `STEPS` in `cli/epic-state.mjs` (E4).
99
- A row says which phase the step is in, whether it authors an artifact or gates one, which file it
98
+ Every one of those ids is defined in **one place** — the lifecycle default that ships with yadflow,
99
+ `cli/lifecycle/defaults/1.json` (E134). The engine reads it as `STEPS` in `cli/epic-state.mjs` (E4):
100
+ there, each author step with a gate becomes two rows, the step and its `<id>-review` gate. A row says which phase the step is in, whether it authors an artifact or gates one, which file it
100
101
  writes, which skill runs it, and — for a gate — which step it reviews. The phase table, the skill
101
102
  tables and the Build order are all views of it, held to it by tests, so a step cannot exist in one and
102
103
  be missing from another.
103
104
 
104
- The catalogue is code. Nothing about it is written into `state.json`, so no file shape changed.
105
+ The catalogue ships inside the package. Nothing about it is written into `state.json`, so no file
106
+ shape changed. A shipped default never changes: a new default is a new file (`2.json`).
105
107
 
106
108
  **The one column a project overrides is the skill.** Which skill runs a step is not a fact about the
107
109
  lifecycle — it depends on what a team installed — so it lives in `.sdlc/skills.json`, a Product-level
@@ -161,7 +163,9 @@ marked N/A that this epic's route does not mark optional. An id the catalogue do
161
163
  ### Lifecycle profiles
162
164
 
163
165
  A **profile** is a named, ordered chain of catalogue steps — the route an epic takes. Six are
164
- defined, in `LIFECYCLE_PROFILES` (`cli/epic-state.mjs`, E5). `classic`, `analysis-first` and `discovery`
166
+ defined, as the `routes` of the same lifecycle default, and the engine reads them as `LIFECYCLE_PROFILES`
167
+ (`cli/epic-state.mjs`, E5). The default holds one more route, `lane` — the Build order one story walks
168
+ in one repo — which is not a profile. `classic`, `analysis-first` and `discovery`
165
169
  are routes the skills already seeded by hand; the two short lanes (E40) and `foundation` (E75) came later:
166
170
 
167
171
  | Profile | Steps | Seeded by |