yadflow 4.5.2 → 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.
- package/CHANGELOG.md +206 -0
- package/README.md +4 -1
- package/bin/commands.mjs +5 -1
- package/bin/yad.mjs +174 -18
- package/cli/artifact-status.mjs +88 -20
- package/cli/build.mjs +1372 -0
- package/cli/checkpoint.mjs +2 -2
- package/cli/commit.mjs +1 -0
- package/cli/dial.mjs +21 -1
- package/cli/docs.mjs +6 -1
- package/cli/doctor.mjs +133 -26
- package/cli/epic-state.mjs +396 -123
- package/cli/errors.mjs +2 -0
- package/cli/find-product.mjs +36 -2
- package/cli/fold.mjs +9 -5
- package/cli/gate-local.mjs +9 -1
- package/cli/gate.mjs +442 -33
- package/cli/history.mjs +22 -2
- package/cli/hook.mjs +3 -1
- package/cli/index-command.mjs +2 -2
- package/cli/ledger.mjs +60 -0
- package/cli/lib.mjs +12 -1
- package/cli/lifecycle/defaults/1.json +96 -0
- package/cli/lifecycle/lifecycle.schema.json +121 -0
- package/cli/lifecycle.mjs +695 -0
- package/cli/next.mjs +34 -11
- package/cli/openpr.mjs +81 -5
- package/cli/platform.mjs +21 -0
- package/cli/pr-list.mjs +49 -3
- package/cli/product-index.mjs +6 -3
- package/cli/product-token.mjs +186 -0
- package/cli/productcommit.mjs +33 -0
- package/cli/recommend.mjs +3 -1
- package/cli/repo-publish.mjs +2 -2
- package/cli/run-checks.mjs +586 -0
- package/cli/ship-drift.mjs +384 -0
- package/cli/standup.mjs +1 -1
- package/cli/status.mjs +282 -0
- package/cli/test-build.mjs +1559 -0
- package/cli/test-run-checks.mjs +603 -0
- package/cli/test-worktree.mjs +520 -0
- package/cli/thread.mjs +50 -3
- package/cli/tidy.mjs +2 -2
- package/cli/toolbox.mjs +36 -5
- package/cli/workspace.mjs +4 -1
- package/cli/worktree-record.mjs +53 -0
- package/cli/worktree.mjs +379 -0
- package/package.json +4 -3
- package/skills/sdlc/config.yaml +28 -20
- package/skills/sdlc/module-help.csv +1 -1
- package/skills/yad-backfill/references/backfill.md +8 -1
- package/skills/yad-backfill/templates/checks/backfill-check.sh +54 -6
- package/skills/yad-change/SKILL.md +3 -0
- package/skills/yad-checks/SKILL.md +47 -5
- package/skills/yad-checks/references/check-gates.md +124 -12
- package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
- package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
- package/skills/yad-checks/templates/checks/contract-check.sh +354 -48
- package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
- package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
- package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
- package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
- package/skills/yad-checks/templates/checks/package-manager.sh +41 -4
- package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
- package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
- package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
- package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
- package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
- package/skills/yad-checks/templates/github/yad-checks.yml +8 -8
- package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
- package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
- package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
- package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
- package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
- package/skills/yad-commit/SKILL.md +4 -2
- package/skills/yad-docs/templates/app/package-lock.json +395 -106
- package/skills/yad-docs/templates/app/package.json +2 -2
- package/skills/yad-engineer-review/SKILL.md +45 -20
- package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
- package/skills/yad-epic/references/state-schema.md +83 -20
- package/skills/yad-implement/SKILL.md +75 -13
- package/skills/yad-implement/references/implement-conventions.md +8 -1
- package/skills/yad-implement/templates/.gitmessage +3 -0
- package/skills/yad-open-pr/SKILL.md +21 -0
- package/skills/yad-pr-template/SKILL.md +6 -2
- package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
- package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
- package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
- package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
- package/skills/yad-product-bridge/SKILL.md +14 -1
- package/skills/yad-product-bridge/references/bridge.md +29 -5
- package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
- package/skills/yad-reconcile/SKILL.md +30 -0
- package/skills/yad-review-gate/SKILL.md +8 -2
- package/skills/yad-review-gate/references/gating.md +26 -1
- package/skills/yad-run/SKILL.md +52 -28
- package/skills/yad-run/references/run-loop.md +42 -21
- package/skills/yad-spec/SKILL.md +142 -17
- package/skills/yad-spec/references/spec-handoff.md +68 -5
- package/skills/yad-status/SKILL.md +7 -0
- package/skills/yad-stories/references/story-schema.md +1 -1
package/skills/sdlc/config.yaml
CHANGED
|
@@ -42,26 +42,27 @@ document_output_language: English
|
|
|
42
42
|
#
|
|
43
43
|
# A phase is DERIVED from a step's id and is never written into `state.json` — there is nothing to
|
|
44
44
|
# author here, nothing to keep in step, and no way for it to disagree with the step it describes.
|
|
45
|
-
#
|
|
46
|
-
# people read. A review gate takes the phase of the artifact it reviews, so `epic-review` is Discover.
|
|
45
|
+
# The phase of each step is set in the lifecycle default (`cli/lifecycle/defaults/1.json`), which
|
|
46
|
+
# `stepPhase` in cli/epic-state.mjs reads; this block is generated from it for people to read. A review gate takes the phase of the artifact it reviews, so `epic-review` is Discover.
|
|
47
47
|
#
|
|
48
48
|
# Release and Operate are NAMED and not built. No step, skill or gate exists for either yet.
|
|
49
49
|
#
|
|
50
50
|
# NOTE the word: "phase" here means one of these six. It does NOT mean the numbered development
|
|
51
51
|
# phases of yadflow itself (docs/phase-N-build-plan.md), which is what "Phase 4a/4b" means elsewhere
|
|
52
52
|
# in these files, nor a gate's internal merge phase.
|
|
53
|
-
# The step CATALOGUE
|
|
54
|
-
#
|
|
55
|
-
#
|
|
56
|
-
#
|
|
57
|
-
#
|
|
58
|
-
#
|
|
59
|
-
#
|
|
53
|
+
# The step CATALOGUE is the lifecycle default that ships with yadflow, `cli/lifecycle/defaults/1.json`
|
|
54
|
+
# (E134; the engine reads it as `STEPS` in `cli/epic-state.mjs`). It is the one place that says what a
|
|
55
|
+
# step is: its phase, whether it authors or gates, what artifact it writes, which skill runs it, and
|
|
56
|
+
# which step a gate reviews. The lines between the `generated` markers below are written from it by
|
|
57
|
+
# `scripts/lifecycle-config.mjs`, and a test fails when they differ; everything else about a step is
|
|
58
|
+
# read from the default, not from here. `yad doctor` reports a project chain that disagrees with the
|
|
59
|
+
# catalogue and rewrites nothing — for this whole major the FILE wins (rule 3): a project may hold a step
|
|
60
|
+
# from a newer yadflow, or a chain written by hand. `yad epic new` seeds a chain from its route (E5, E17).
|
|
60
61
|
lifecycle:
|
|
61
|
-
|
|
62
|
-
#
|
|
63
|
-
# `
|
|
64
|
-
# `classic` (the 10-step chain, `epic` first — yad-epic / yad-stub / yad-change), `analysis-first`
|
|
62
|
+
# Lifecycle PROFILES (E5) — the route an epic takes through the steps, defined as the `routes` of the
|
|
63
|
+
# lifecycle default and read by the engine as `LIFECYCLE_PROFILES` (`cli/epic-state.mjs`). The
|
|
64
|
+
# default's `lane` route (the Build order) is not a profile, so it is not in `profiles`. Three were
|
|
65
|
+
# routes the skills already seeded by hand: `classic` (the 10-step chain, `epic` first — yad-epic / yad-stub / yad-change), `analysis-first`
|
|
65
66
|
# (the 12-step chain, `analysis` before `epic` — yad-analysis) and `discovery` (the product
|
|
66
67
|
# front-zero — yad-discovery, now the OLD spelling of the Product level). `foundation` is that level
|
|
67
68
|
# as E75 writes it — `yad foundation new`. Two are the short lanes E40 added, which nobody seeded before:
|
|
@@ -72,9 +73,13 @@ lifecycle:
|
|
|
72
73
|
# field `yad migrate` fills it in by matching the chain. The chain stays the truth — `yad doctor`
|
|
73
74
|
# compares the two. NOT the `product.json` `profile`, which is the unrelated setup record
|
|
74
75
|
# { codebase, repo_layout, team_size }.
|
|
76
|
+
# The PRODUCT level's phase (E75), `product_phases` — a ladder of its own, run once per product before
|
|
77
|
+
# any epic, and part of no Part. `discovery` is listed because it is the old spelling of the same level.
|
|
78
|
+
# Release and Operate are planned: E32 builds Release, E33 builds Operate.
|
|
79
|
+
# `sentinels` are `currentStep` markers that are NOT steps: they never appear in `steps[]` and have no phase.
|
|
80
|
+
# >>> generated: lifecycle — from cli/lifecycle/defaults/1.json by scripts/lifecycle-config.mjs; do not edit by hand
|
|
81
|
+
parts: [Shape, Build, Run]
|
|
75
82
|
profiles: [classic, analysis-first, chore, spike, discovery, foundation]
|
|
76
|
-
# The PRODUCT level's phase (E75) — a ladder of its own, run once per product before any epic, and
|
|
77
|
-
# part of no Part. `discovery` is listed because it is the old spelling of the same level.
|
|
78
83
|
product_phases:
|
|
79
84
|
- { id: foundation, name: Foundation, level: product, built: true, steps: [foundation, discovery] }
|
|
80
85
|
phases:
|
|
@@ -82,10 +87,10 @@ lifecycle:
|
|
|
82
87
|
- { id: design, name: Design, part: Shape, built: true, steps: [architecture, ui-design] }
|
|
83
88
|
- { id: plan, name: Plan, part: Shape, built: true, steps: [stories, test-cases] }
|
|
84
89
|
- { id: build, name: Build, part: Build, built: true, steps: [spec, tasks, implement, checks, engineer-review] }
|
|
85
|
-
- { id: release, name: Release, part: Run, built: false, steps: [] }
|
|
86
|
-
- { id: operate, name: Operate, part: Run, built: false, steps: [] }
|
|
87
|
-
# `currentStep` markers that are NOT steps: they never appear in `steps[]` and have no phase.
|
|
90
|
+
- { id: release, name: Release, part: Run, built: false, steps: [] }
|
|
91
|
+
- { id: operate, name: Operate, part: Run, built: false, steps: [] }
|
|
88
92
|
sentinels: [ready-for-build, backfill-pending, backfill-done, discovery-done, foundation-done]
|
|
93
|
+
# <<< generated: lifecycle
|
|
89
94
|
|
|
90
95
|
defaults:
|
|
91
96
|
# The two dials: who does the work, and who moves it forward. Renamed in shape 4; BOTH names are
|
|
@@ -197,7 +202,7 @@ build:
|
|
|
197
202
|
# the separate security gate (a platform-Verified signature only; no author allowlist since E62). All blocking in CI; both repos + Product.
|
|
198
203
|
pattern_gates: [commit-message, pr-title, pr-template]
|
|
199
204
|
ci_platforms: [github, gitlab] # both wired from skills/yad-checks/templates/; GitHub is this product repo's platform
|
|
200
|
-
contract_surface_glob: "specs/*/contracts/**" # the repo's quoted contract slice; a diff here needs Contract-Change + a re-locked contract
|
|
205
|
+
contract_surface_glob: "specs/*/contracts/**" # the repo's quoted contract slice; a diff here needs Contract-Change + a re-locked contract, unless it is an exact CONTRACT-QUOTE of the lock (#344)
|
|
201
206
|
# Step D (yad-pr-template) — platform-matched PR/MR template + risk routing.
|
|
202
207
|
pr_templates:
|
|
203
208
|
github: ".github/pull_request_template.md"
|
|
@@ -214,7 +219,7 @@ build:
|
|
|
214
219
|
# unfolded ship, e.g. a `yad checkpoint --retro-ship` backfill or any ship on an `in-build` story.
|
|
215
220
|
build_log: "epics/EP-<slug>/.sdlc/build-log.json" # folded ships
|
|
216
221
|
build_log_dir: "epics/EP-<slug>/.sdlc/build-log/" # one <story>-<task>-<repo>.json shard per ship
|
|
217
|
-
story_build_states: [in-build, shipped] # in-build = some tasks shipped; shipped = all tasks in tasks.md shipped
|
|
222
|
+
story_build_states: [in-build, shipped] # in-build = some tasks shipped; shipped = all tasks in tasks.md (or a light spec's tasks block) shipped
|
|
218
223
|
# Backfill (yad-backfill) — specs for already-built features in an existing repo.
|
|
219
224
|
backfill:
|
|
220
225
|
tool: repomix # the one true CLI subprocess: `npx repomix@1.18.1` (Phase 0 / RESEARCH-NOTES §3)
|
|
@@ -350,7 +355,10 @@ product:
|
|
|
350
355
|
# stops the file being updated — and nothing reads `kill_switch` now. `yad doctor` fails on one left `true`.
|
|
351
356
|
automation:
|
|
352
357
|
# The only steps that MAY be automated, safest-end first (phase-4-build-plan.md build order).
|
|
358
|
+
# The Build lane's author steps — every lane step but the merge gate, `engineer-review`.
|
|
359
|
+
# >>> generated: back_steps — from cli/lifecycle/defaults/1.json by scripts/lifecycle-config.mjs; do not edit by hand
|
|
353
360
|
back_steps: [spec, tasks, implement, checks]
|
|
361
|
+
# <<< generated: back_steps
|
|
354
362
|
default: human_approve # = `advance: human`. Every lane step starts manual; `yad dial` turns one to auto
|
|
355
363
|
|
|
356
364
|
# Phase 6 (post-lock change management) — FEATURE THREADS. After the contract locks and code ships, a
|
|
@@ -15,7 +15,7 @@ SDLC Workflow,yad-connect-design,Connect Design Tool,CD,"Setup/maintenance: conn
|
|
|
15
15
|
SDLC Workflow,yad-connect-testing,Connect Testing Tool,CT,"Setup/maintenance: connect a testing tool (Playwright-first, pluggable) to the Product so the test-cases step can implement the actual automation tests in it, alongside test-cases.md. Records the tool + project/suite references in .sdlc/testing.json (local-user / MCP-session auth, no stored tokens), detecting whether a testing-tool MCP is available and degrading to artifacts-only when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: playwright|cypress|pytest|none} {project_url: <project/config reference>} {suites: {<repo>}},0-setup,,yad-test-cases,false,.sdlc/,testing.json
|
|
16
16
|
SDLC Workflow,yad-connect-learning,Connect Learning Tool,CL,"Setup/maintenance: connect a learning/tutoring tool (DeepTutor-first, pluggable) so the cross-cutting learning layer can tutor any team member, at any SDLC stage, in the context of what is being built. Records the tool + an optional grounded knowledge base in .sdlc/learning.json (local-user auth, no stored tokens), detecting whether the DeepTutor CLI is on PATH (a subprocess like Repomix, not an MCP) and degrading to harness-native tutoring when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: deeptutor|none} {kb: <name>} {ground: true|false},0-setup,,yad-learn,false,.sdlc/,learning.json
|
|
17
17
|
SDLC Workflow,yad-learn,Learn (Tutor),LN,"Cross-cutting learning layer: at ANY SDLC stage a team member can ask to learn a concept and be tutored in the context of what the team is building. Routes to the connected learning tool (.sdlc/learning.json, DeepTutor-first) grounded in the project knowledge base, or degrades to harness-native tutoring (the harness model reading the artifacts). Renders a tutorial artifact and appends to a per-member learning ledger kept LOCAL-ONLY (gitignored, never committed/pushed to the Product or any code repo) so it stays a private, personal skills log (yad-status rolls up the local records). Purely opt-in — never blocks a gate, never touches epic state, approvals, or the contract lock.",,{concept: <idea>} {context: <focus>} {epic: EP-<slug>} {stage: <sdlc stage>} {member: <who>} {mode: explain|deep|quiz} {action: learn|list|complete},anytime,,,false,epics/EP-<slug>/,learning-records.json learning/<member>--<concept>.md
|
|
18
|
-
SDLC Workflow,yad-spec,Author Spec,SP,"Build Step A: 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 layout (drives /speckit.* when installed, else hand-authors and records speckit: not-installed). References the locked contract; never re-invents the surface. Writes link.md back to the story. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <one of story.repos>},3-build,yad-review-gate,,false,demo-repos/<repo>/specs/<story-id>/,spec.md research.md data-model.md contracts/ plan.md tasks.md link.md
|
|
18
|
+
SDLC Workflow,yad-spec,Author Spec,SP,"Build Step A: 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 layout (drives /speckit.* when installed, else hand-authors and records speckit: not-installed; a light spec for a small story with no contract surface is one spec.md, confirmed by a human, #348). References the locked contract; never re-invents the surface. Writes link.md back to the story. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <one of story.repos>},3-build,yad-review-gate,,false,demo-repos/<repo>/specs/<story-id>/,spec.md research.md data-model.md contracts/ plan.md tasks.md link.md
|
|
19
19
|
SDLC Workflow,yad-implement,Implement Task,IM,"Build Step B: with the dev lens, implement ONE atomic task from a story's tasks.md as a small diff (<=3 files) on its own branch feat/<story>-<task>-<slug> in the code repo. Diff stays inside the task's declared files (flag and STOP if it grows beyond them). Commit ends with a Task: <story>-<task> trailer; add Contract-Change: yes only when the locked contract surface is touched (routes back to the architecture gate). Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <one of story.repos>} {task: T0N},3-build,yad-spec,,false,demo-repos/<repo>/,branch+commit per atomic task
|
|
20
20
|
SDLC Workflow,yad-checks,Check Gates,CK,"Build Step C: wire and run the production-safety CI gates on a code repo (and Product) — spec-link (every change links a real story/spec via its Task trailer), contract-check (a contract-surface change without Contract-Change + an updated re-locked contract FAILS and routes back to the architecture gate), build/test/lint, verified-commits (every commit carries a platform-Verified signature), and the pattern gates commit-message / pr-title / pr-template (profile-aware code|product). CI-agnostic bash invoked by GitHub Actions and GitLab CI. Blocking in CI; the human still owns the merge. Never auto-advances.",,{repo: <one of an epic's repos | product>} {action: wire|run} {base: target branch},3-build,yad-implement,,false,demo-repos/<repo>/,checks/*.sh .github/workflows/yad-checks.yml .gitlab/ci/yad-checks.yml
|
|
21
21
|
SDLC Workflow,yad-pr-template,PR/MR Template,PT,"Build Step D: detect a code repo's platform and commit the matching PR/MR template (.github/pull_request_template.md or .gitlab/merge_request_templates/Default.md) with an Impact & Risk block. A high risk level (or a touched contract surface) raises the approver count — the same count yad-review-gate prints. Ships the routing helper risk-route.sh plus the pattern-gate scripts pr-title.sh and pr-template.sh (used by yad-checks). Never auto-advances.",,{repo: <one of an epic's repos | product>} {action: wire|route} {body: PR description file},3-build,yad-checks,,false,demo-repos/<repo>/,.github/pull_request_template.md .gitlab/merge_request_templates/Default.md checks/risk-route.sh checks/pr-title.sh checks/pr-template.sh
|
|
@@ -58,7 +58,14 @@ follow the convention. Never finalise a boundary silently.
|
|
|
58
58
|
|
|
59
59
|
## The gate — `checks/backfill-check.sh`
|
|
60
60
|
|
|
61
|
-
A change is blocked **only until the features it touches** have approved specs — not the whole repo
|
|
61
|
+
A change is blocked **only until the features it touches** have approved specs — not the whole repo.
|
|
62
|
+
"The features it touches" are what merging the branch into the target would change (issue #363):
|
|
63
|
+
`git merge-tree --write-tree <base> HEAD` (git 2.38+), diffed from the target. A file that changed on the
|
|
64
|
+
target after the branch split off is not this branch's change; a file the target renamed into a feature
|
|
65
|
+
that the branch edits at its old path IS (the merge carries the edit there); and with several merge bases
|
|
66
|
+
nothing a hand-resolved merge undid is missed. A branch that does not merge cleanly, or a base that shares
|
|
67
|
+
no history with HEAD (a shallow clone), **FAILS** closed. An older git reads from the merge base and fails
|
|
68
|
+
closed on several merge bases, or when the target removed or moved a file the branch modifies.
|
|
62
69
|
|
|
63
70
|
- For each `src/<feature>/` the diff touches, if `specs/backfill/<feature>/spec.md` exists it must be
|
|
64
71
|
`verified: true`; otherwise **FAIL** (run backfill + approve for that feature first).
|
|
@@ -24,7 +24,7 @@ product_config() {
|
|
|
24
24
|
if [ -n "${SDLC_PRODUCT_CONFIG:-}" ]; then printf '%s' "$SDLC_PRODUCT_CONFIG"; return 0; fi
|
|
25
25
|
if [ -n "${SDLC_HUB_CONFIG:-}" ]; then printf '%s' "$SDLC_HUB_CONFIG"; return 0; fi
|
|
26
26
|
if [ -f .sdlc/product.json ] && [ -f .sdlc/hub.json ] && ! cmp -s .sdlc/product.json .sdlc/hub.json; then
|
|
27
|
-
echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5.
|
|
27
|
+
echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5. In the Product, run \`yad migrate --apply --keep product\` (or \`--keep hub\`) to choose the copy to keep, then commit both files." >&2
|
|
28
28
|
return 1
|
|
29
29
|
fi
|
|
30
30
|
if [ -f .sdlc/product.json ]; then printf '%s' .sdlc/product.json; else printf '%s' .sdlc/hub.json; fi
|
|
@@ -61,9 +61,57 @@ resolve_base() {
|
|
|
61
61
|
BASE="${1:-${SDLC_BASE:-$(resolve_base)}}"
|
|
62
62
|
[ -n "${1:-}" ] || [ -n "${SDLC_BASE:-}" ] || echo "note [backfill]: no base given — diffing against '${BASE}'."
|
|
63
63
|
if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
|
|
64
|
-
echo "FAIL [backfill]: base ref '${BASE}' not found —
|
|
64
|
+
echo "FAIL [backfill]: base ref '${BASE}' not found — check the code out with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), and give a base that names a fetched branch (the first argument, or SDLC_BASE)."
|
|
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 — a shallow clone has no merge base: check the code out with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), or give the branch this change targets as the base."
|
|
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}) — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), 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 — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again. Git 2.38 or newer on the runner builds the merge instead and skips this step."; 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 since it split off from '${BASE}' — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again. Git 2.38 or newer on the runner builds the merge instead and skips this step."; 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
|
|
@@ -92,7 +140,7 @@ FOLD='function fold(x) { x = tolower(x)
|
|
|
92
140
|
# `tr '\n\0' '?\n'`: one record per line, and a newline inside a path becomes `?` — split on newlines
|
|
93
141
|
# alone, a file named `notes<newline>100644 blob 0<TAB>src/Billing/y` added a record nobody made (review 2).
|
|
94
142
|
base_tree="$(git ls-tree -r -z --full-tree "$BASE" | tr '\n\0' '?\n')" || {
|
|
95
|
-
echo "FAIL [backfill]: git could not read the tree of '${BASE}'
|
|
143
|
+
echo "FAIL [backfill]: git could not read the tree of '${BASE}', so the gate cannot tell which features are being backfilled — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again."
|
|
96
144
|
exit 1
|
|
97
145
|
}
|
|
98
146
|
# One line each: `S <oid> <path>` a spec to read, `U - <path>` a link where a spec goes, `A - <path>` a
|
|
@@ -125,7 +173,7 @@ bf="$(printf '%s\n' "$specs" | sed -n 's/^[SU] [^ ]* //p' | awk "$FOLD"'{ split(
|
|
|
125
173
|
# empty.
|
|
126
174
|
tagged() { printf '%s\n' "$2" | awk -v t="$1" 'length($0) { print t "\t" $0 }'; }
|
|
127
175
|
head_tree="$(git ls-tree -r -z --full-tree HEAD | tr '\n\0' '?\n')" || {
|
|
128
|
-
echo "FAIL [backfill]: git could not read the tree at HEAD
|
|
176
|
+
echo "FAIL [backfill]: git could not read the tree at HEAD, so the gate cannot check src/ for links — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again."
|
|
129
177
|
exit 1
|
|
130
178
|
}
|
|
131
179
|
if [ -n "$bf" ] || [ -n "$blind" ]; then
|
|
@@ -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 "$
|
|
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
|
|
221
|
+
echo "FAIL [backfill]: git could not list what this branch changes in '${BASE}' — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again."
|
|
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.
|
|
@@ -257,6 +257,9 @@ again. Unbound, that command names `yad-architecture` for a contract-surface cha
|
|
|
257
257
|
## Hard rules
|
|
258
258
|
|
|
259
259
|
- **Never mutate a locked artifact.** A change is a new threaded epic, not an edit to a shipped one.
|
|
260
|
+
The one exception is BEFORE Build begins — no story has a Build lane and nothing has shipped: then
|
|
261
|
+
reopen the approved step with `yad gate reopen <epic> <step> --reason "<why>"` (#322) instead of
|
|
262
|
+
threading a change epic; every gate from that step is approved again.
|
|
260
263
|
- **A change MUST thread to a real parent.** Validate the parent + thread first; STOP on a broken lineage.
|
|
261
264
|
- **Inherit by reference, never copy.** `yad epic new --parent` carries inherited steps as `satisfied` with
|
|
262
265
|
`inherited: true` + a `boundHash`; the pointer-lock carries the owner's hash verbatim. The gate never
|
|
@@ -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
|
|
@@ -25,6 +38,8 @@ in CI on every PR/MR and must pass before merge (build plan §C). Each is a smal
|
|
|
25
38
|
Product lives is a repo fact once `yad check --fix --push` has merged `.sdlc/product-link.json` into
|
|
26
39
|
the code repo (E120): the gates read it from the base first, and `checks/product-checkout.sh` clones
|
|
27
40
|
the Product there in CI when the `YAD_PRODUCT_TOKEN` secret is set (see `references/check-gates.md`).
|
|
41
|
+
A missing token on a PR that is not from a fork is a `WARNING` in CI, and a token that expires within
|
|
42
|
+
30 days is warned about there too (#345); `yad doctor` reports where each code repo's CI gets it.
|
|
28
43
|
3. **build/test/lint** — standard quality stage; tests must actually exercise new behavior, not just pass.
|
|
29
44
|
CI installs and runs through the package manager declared by the repo's standard
|
|
30
45
|
`package.json#packageManager` field (`npm` and `pnpm` are supported; any other manager stays on
|
|
@@ -67,7 +82,7 @@ from CI. `product-repo` is read from the base, a Product this repo tracks is rea
|
|
|
67
82
|
`epic:` must be the story ID's prefix — the PR cannot choose what is gated (E117, E118). See `references/check-gates.md` and `skills/yad-change`.
|
|
68
83
|
|
|
69
84
|
The gates are **CI-agnostic bash** in `checks/`; thin pipeline configs invoke them on GitHub Actions
|
|
70
|
-
and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the skill or let CI run them;
|
|
85
|
+
and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the skill (`yad run checks`) or let CI run them;
|
|
71
86
|
**nothing auto-advances**. The gates are blocking in CI (all but the advisory risk-map check), but the human still owns the merge (Step E).
|
|
72
87
|
|
|
73
88
|
## Conventions
|
|
@@ -179,12 +194,34 @@ Copy from this skill's `templates/`:
|
|
|
179
194
|
- The legacy standalone `templates/gitlab/.gitlab-ci.yml` is retained only for a clean greenfield repo
|
|
180
195
|
that prefers a single self-contained file; the include path above is the default.
|
|
181
196
|
- **Tag-locked runners** (`run_untagged: false`, common on self-hosted): the fragment's jobs run a
|
|
182
|
-
docker image, so set a `YAD_RUNNER_TAGS` CI/CD variable (e.g. `dind_runner`) to route them —
|
|
183
|
-
|
|
197
|
+
docker image, so set a `YAD_RUNNER_TAGS` CI/CD variable (e.g. `dind_runner`) to route them — every
|
|
198
|
+
GitLab fragment's jobs carry `tags: [$YAD_RUNNER_TAGS]`. When unset, current GitLab (≥15) drops the
|
|
184
199
|
empty-expanded tag so the jobs run untagged (gitlab.com shared runners); older versions may
|
|
185
200
|
strand them `pending`, in which case set the variable to a real tag. The variable lives in
|
|
186
201
|
project settings, so it survives every `yad` sync. Single value only — `tags: [$VAR]` is one tag
|
|
187
|
-
equal to the whole variable, not a comma-split.
|
|
202
|
+
equal to the whole variable, not a comma-split. Leave **Protect variable** unticked on both
|
|
203
|
+
variables below: a protected variable reaches only pipelines on protected branches, so the MR
|
|
204
|
+
gates would run without it — untagged and on the default Node line.
|
|
205
|
+
- **The Node line** (#364): every GitLab job runs `image: node:${YAD_NODE_VERSION}`, `22` by default.
|
|
206
|
+
Set a `YAD_NODE_VERSION` CI/CD variable (a current `20`, `22` or `24` line) to change it — a
|
|
207
|
+
project variable wins over the fragment's value, so the fragment itself is never edited.
|
|
208
|
+
- **Shell-executor runners** ignore `image:`. The jobs then run on the runner host as they are, so
|
|
209
|
+
the host needs `bash`, `git`, `curl` (the signature gates read the GitLab API with it; without it
|
|
210
|
+
every commit reads as unverified) and Node (any current 20, 22 or 24 line — for example from nvm)
|
|
211
|
+
on the runner user's `PATH`, plus whatever the repo's own build needs (Corepack, pnpm, …) for
|
|
212
|
+
`build-test-lint`. `YAD_NODE_VERSION` has no effect there. Point `YAD_RUNNER_TAGS` at that
|
|
213
|
+
runner's tag.
|
|
214
|
+
- **Do not hand-edit the fragments to fit a runner.** They are managed bytes: `yad check` reports a
|
|
215
|
+
hand-edited one as `modified`, and a plain `yad update` leaves it alone — so it never receives a
|
|
216
|
+
fix again. Both runner settings above are CI/CD variables, so no edit is needed: move the
|
|
217
|
+
customisation into them, then run `yad update --overwrite-local` to restore the fragment (it keeps
|
|
218
|
+
a `.yad-orig` copy of the edited one first). `yad doctor` warns when a wired
|
|
219
|
+
fragment has no `tags:` (`YAD-CI-001`) or still runs a fixed `node:<n>` image (`YAD-CI-002`, an
|
|
220
|
+
install from before the variable — `yad update` replaces it).
|
|
221
|
+
- **Product jobs of your own** (`yad-product-checks.yml`): before #364 this fragment set its image
|
|
222
|
+
and tag in a top-level `default:`, which GitLab applies to every job in the pipeline — the
|
|
223
|
+
Product's own jobs too. They now sit on the yad jobs only. A job of yours that had no `image:` or
|
|
224
|
+
`tags:` and relied on that block needs its own after `yad update`.
|
|
188
225
|
|
|
189
226
|
- Ensure `<repo>/package.json` defines `lint`, `build`, `test` scripts (see `references/check-gates.md`
|
|
190
227
|
for the canonical scripts). **Only ADD a missing script; never overwrite an existing one.**
|
|
@@ -257,7 +294,12 @@ it. Branch protection is what makes the CI gates hold a merge at all: point the
|
|
|
257
294
|
`docs/branch-protection.md`.
|
|
258
295
|
|
|
259
296
|
### Step 3 — `run` (run the gates now)
|
|
260
|
-
From inside the repo, run
|
|
297
|
+
From inside the repo, run `yad run checks` (add `--body <file>` holding the PR/MR description, and
|
|
298
|
+
`--title` unless the branch has exactly one commit). It runs every installed gate as CI does — the
|
|
299
|
+
Product's default branch where CI checks it out, every gate even after one fails — and prints a summary;
|
|
300
|
+
report PASS, FAIL or skipped per gate from it (`--json` lists each gate's FAIL lines). A skipped
|
|
301
|
+
pr-title or pr-template is not a pass. It runs `npm ci` (which replaces `node_modules`) and the build;
|
|
302
|
+
add `--no-build` when that is not wanted. One gate by hand:
|
|
261
303
|
```
|
|
262
304
|
bash checks/spec-link.sh "<base>"
|
|
263
305
|
bash checks/contract-check.sh "<base>"
|
|
@@ -4,6 +4,9 @@ The gates are the production-safety core of Build (Phase 3 build plan §C). They
|
|
|
4
4
|
deliberately small, separate, and CI-agnostic: plain bash in `checks/`, invoked by whatever CI the
|
|
5
5
|
repo uses. Each reads conventions established by earlier steps — it invents nothing.
|
|
6
6
|
|
|
7
|
+
For people, `docs/GATES.md` in the yadflow repo lists every gate's rules, exemptions and failure
|
|
8
|
+
messages, with what to change for each. When a gate's rule or message changes, update that page too.
|
|
9
|
+
|
|
7
10
|
## What each gate reads (the convention map)
|
|
8
11
|
|
|
9
12
|
| Gate | Reads | Source step |
|
|
@@ -75,6 +78,18 @@ Every gate stops on its failure except **risk-map**, which is advisory: there a
|
|
|
75
78
|
A maintenance commit that *does* carry a `Task:` trailer is resolved like any other: a malformed id
|
|
76
79
|
or a missing `specs/<story>/link.md` **FAILS**. Otherwise the trailer is decorative on exempt
|
|
77
80
|
commits and an unlinked `chore:` is indistinguishable from one naming a story that never existed.
|
|
81
|
+
- **SHA exemption** (shared with lineage-check, epic-open and reconcile-debt — one byte-identical block).
|
|
82
|
+
A commit listed in `.sdlc/gate-exempt` (or `SDLC_GATE_EXEMPT`; one full hex SHA per line — 40
|
|
83
|
+
characters, 64 in a SHA-256 repo, `#` comments; a short SHA is refused, as a tag of that name would stand in for it) **PASSes** before anything else is judged,
|
|
84
|
+
so it skips every check of the four gates, not only the trailer's. `SDLC_GATE_EXEMPT` comes from the
|
|
85
|
+
pipeline config, which a PR may edit; it still names a file on the base, so it cannot list the PR's
|
|
86
|
+
own commits, and guarding the pipeline itself is branch protection's job. It is for history already on a shared
|
|
87
|
+
branch whose trailer cannot be reworded — otherwise every later range that holds it, a release PR
|
|
88
|
+
above all, fails again. The list is read **from the base**, never from the PR, so a PR cannot waive
|
|
89
|
+
its own commits. An entry exempts nothing, and is said as a note, when it is a branch or tag name, a
|
|
90
|
+
short SHA, a SHA of the wrong length for this repo (64 characters in a SHA-1 repo, 40 in a SHA-256
|
|
91
|
+
one — git would look it up as a ref name), an annotated tag's or a tree's SHA, or a SHA that names no
|
|
92
|
+
object here.
|
|
78
93
|
- For every other commit, requires a `Task: <story>-<task>` trailer. **FAIL** if absent.
|
|
79
94
|
- The trailer must be a well-formed `<story>-T<NN>` id. **FAIL** on a malformed trailer (e.g.
|
|
80
95
|
`EP-demo-S01` with no `-T<NN>`) rather than letting it slip through the suffix-strip.
|
|
@@ -125,13 +140,66 @@ Every gate stops on its failure except **risk-map**, which is advisory: there a
|
|
|
125
140
|
`yad-spec` writes real files, so nothing legitimate lives there as a link. Removing a link under
|
|
126
141
|
`contracts/` is a change to the surface and needs `Contract-Change: yes`; on a lockless epic it takes
|
|
127
142
|
the removal hatch below. `yad doctor` warns `checks:symlink-blind` for an older copy without this check.
|
|
128
|
-
- Computes the changed files
|
|
143
|
+
- Computes the changed files as **what merging the branch into the target would change** (issue #363):
|
|
144
|
+
`git merge-tree --write-tree <base> HEAD` (git 2.38+) builds that merge without touching anything, and
|
|
145
|
+
the diff runs from the target to it — what GitHub's own merge checkout gives. The quote pass reads the
|
|
146
|
+
slice's content, and the "whole slice removed" check its tree, from that result too. Why the merge and
|
|
147
|
+
not a simpler range:
|
|
148
|
+
- a two-dot diff compared with the target's tip, so a slice that landed on the target after the branch
|
|
149
|
+
split off failed a branch that never touched it;
|
|
150
|
+
- a diff from the merge base reads from ONE merge base when there are several (a hotfix merged into
|
|
151
|
+
both, stacked branches, a criss-cross merge), so a hand-resolved merge could undo what the other
|
|
152
|
+
side brought in (review 1);
|
|
153
|
+
- and it misses a **rename** on the target: the real merge follows it, so an edit to a file the target
|
|
154
|
+
moved into a slice (or a backfilled feature) lands there unseen (review 4).
|
|
155
|
+
|
|
156
|
+
The trailer is still read from `git log <base>..HEAD` (this branch's own commits), and so are the
|
|
157
|
+
slice files **the branch's own commits touch** (merge commits left out, the full history read so a
|
|
158
|
+
merged side's commits are not dropped): they count as touched even when the merge nets them to nothing
|
|
159
|
+
(review 5, the user's decision). A GitHub "Rebase and merge" replays each commit, so a commit that
|
|
160
|
+
mirrors the target's re-lock and a later one that undoes it would land the undo while the merge shows
|
|
161
|
+
no change. So when the branch's own commits touch a slice, **the quote proof also needs the branch
|
|
162
|
+
rebased onto the target, with no merge commits** (review 6): then every merge method lands the branch
|
|
163
|
+
tip, which is the merge the gate reads, and the proof is exact. Otherwise the gate says to rebase (or
|
|
164
|
+
add the trailer). Both paths read the `link.md` that lands, from the merge. A story "only removes" its
|
|
165
|
+
slice when every slice path it touches is gone from what lands.
|
|
166
|
+
A branch that does not merge cleanly **FAILS** closed (the platform cannot merge it either): merge the
|
|
167
|
+
target into it. A base that shares no history with HEAD (a shallow clone), or a merge git cannot build
|
|
168
|
+
(a missing object), **FAILS** closed. **Older git** (before 2.38) falls back to the merge base,
|
|
169
|
+
`<base>...HEAD`, and fails closed when there is more than one, or when the target **removed or moved**
|
|
170
|
+
a file the branch modifies (no rename detection: its limits differ from the merge's).
|
|
129
171
|
- The surface is `specs/<story>/contracts` **and** everything under it: a path that IS
|
|
130
172
|
`specs/<story>/contracts` (a link being removed) counts too.
|
|
131
173
|
- If **nothing** under `specs/*/contracts/**` changed → **PASS** (normal implementation only *consumes*
|
|
132
174
|
the contract).
|
|
133
175
|
- If the surface slice changed:
|
|
134
|
-
- Require a `Contract-Change: yes` trailer. **FAIL** (route back to the architecture gate) if absent
|
|
176
|
+
- Require a `Contract-Change: yes` trailer. **FAIL** (route back to the architecture gate) if absent —
|
|
177
|
+
**unless every touched story's slice is an exact quote** (issue #344). A story's slice is a quote
|
|
178
|
+
when all of these hold, and the failure lists each one that does not:
|
|
179
|
+
- the story's folder is a story ID and its `link.md` is there;
|
|
180
|
+
- the Product is reached (the same resolution as below) and its `contract-lock.json` is readable;
|
|
181
|
+
- `link.md` pins that lock's hash;
|
|
182
|
+
- the Product's `epics/<epic>/contract.md` still hashes to the lock (the `CONTRACT-SURFACE` recipe),
|
|
183
|
+
so the lines are compared with the **locked** text, not a later edit. A change-epic that inherits
|
|
184
|
+
its architecture has a **pointer lock** (`inheritedFrom` / `ref`) and no `contract.md`: the owner's
|
|
185
|
+
`contract.md` is read instead, only inside the Product's `epics/`, and only while the owner's lock
|
|
186
|
+
still holds the copied hash. An epic that re-authored its architecture and kept the pointer fields
|
|
187
|
+
has its own `contract.md`, and that is read (`yad doctor` reads it too, and also warns about the
|
|
188
|
+
leftover fields);
|
|
189
|
+
- no slice file is deleted (a deletion changes the surface);
|
|
190
|
+
- every changed slice file is **Markdown** (`.md`; any other file under `contracts/` needs the
|
|
191
|
+
trailer), read from the commit by its exact name (a name holding a newline, or content holding a
|
|
192
|
+
zero byte, is refused), and holds **exactly one** `<!-- CONTRACT-QUOTE:BEGIN -->` …
|
|
193
|
+
`<!-- CONTRACT-QUOTE:END -->` block, not empty. Its non-blank lines (trailing spaces and a CR
|
|
194
|
+
ignored) are **one unbroken run of the locked surface's non-blank lines, in its order** — lines
|
|
195
|
+
checked one by one could be reordered into a different meaning (review 1), and two blocks, each a
|
|
196
|
+
run, could be stitched into one (review 2); to quote two parts, use two files. Outside the block the
|
|
197
|
+
file holds only blank lines and, as its first non-blank line, the optional title
|
|
198
|
+
`# Contract slice — <story ID>` (exactly that text; a leading BOM is ignored): a note there was never
|
|
199
|
+
read, so a new endpoint written in it passed (review 1), and a free title could say anything
|
|
200
|
+
(review 2). Notes go in `spec.md` or `plan.md`.
|
|
201
|
+
A prose slice from before this rule has no block, so it still needs the trailer until `yad-spec`
|
|
202
|
+
rewrites it.
|
|
135
203
|
- Best-effort fidelity: when the product repo is reachable (via `link.md`'s `product-repo` path),
|
|
136
204
|
require `link.md`'s pinned `contract-lock` hash to match the product repo's current
|
|
137
205
|
`contract-lock.json`. A claimed change that still pins the **old** lock **FAILS** — re-run
|
|
@@ -307,7 +375,9 @@ from the event payload):
|
|
|
307
375
|
pass — it has no EP artifact to review.
|
|
308
376
|
- **Anti-bypass guard.** The branch name alone is not trusted: a non-review head that actually
|
|
309
377
|
changes Shape artifacts (any path under `epics/**` or `foundation/**`) **FAILS** — those changes must go through
|
|
310
|
-
a `review/EP-*` PR and the artifact-review workflow.
|
|
378
|
+
a `review/EP-*` PR and the artifact-review workflow. The message says how: move them to a
|
|
379
|
+
`review/<epic>/<artifact>` branch (`review/EP-foundation/foundation` for the Foundation) and run
|
|
380
|
+
`yad open-pr` from it, or drop them from the PR. CI passes the PR's changed paths via
|
|
311
381
|
`--changed <file>` (computed from the diff against the base ref); without that list (a direct
|
|
312
382
|
by-hand caller) the guard is inert and the branch split alone applies. A step owner file
|
|
313
383
|
(`epics/<epic>/.sdlc/owners/<step>.json`, `foundation/.sdlc/owners/…`, written by `yad assign`,
|
|
@@ -331,18 +401,36 @@ catches a free-form description that bypassed it:
|
|
|
331
401
|
`## Impact & Risk`, `## Checklist`, filled `Risk level:`).
|
|
332
402
|
- **Anti-bypass guard** (same as pr-title): a non-review head that changes Shape artifacts
|
|
333
403
|
(`epics/**` or `foundation/**`, detected from the CI-supplied `--changed <file>` list) **FAILS** — artifact changes
|
|
334
|
-
must go through a `review/EP-*` PR. Step owner files alone do not count (E47).
|
|
404
|
+
must go through a `review/EP-*` PR, and the message says how, as in pr-title. Step owner files alone do not count (E47).
|
|
335
405
|
|
|
336
406
|
**GitLab truncates the description this gate reads.** `$CI_MERGE_REQUEST_DESCRIPTION` stops at **2700
|
|
337
407
|
characters**, so a long but perfectly valid MR can lose a required section *before the gate sees it* —
|
|
338
408
|
the author then reads "does not use the template" while looking at a description that visibly contains
|
|
339
|
-
it (#164). GitHub is unaffected (`github.event.pull_request.body` is not truncated).
|
|
340
|
-
|
|
409
|
+
it (#164). GitHub is unaffected (`github.event.pull_request.body` is not truncated). Three mitigations,
|
|
410
|
+
all shipped:
|
|
411
|
+
|
|
412
|
+
- **the gate reads the whole description (#343).** In GitLab CI, when GitLab says it cut the description
|
|
413
|
+
(`CI_MERGE_REQUEST_DESCRIPTION_IS_TRUNCATED`) or the text it was handed has reached 2700 characters, the
|
|
414
|
+
gate reads it again in full from the merge request API
|
|
415
|
+
(`$CI_API_V4_URL/projects/$CI_MERGE_REQUEST_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID`) and checks
|
|
416
|
+
that instead. The token is the `GITLAB_TOKEN` (or `SDLC_API_TOKEN`) CI/CD variable — the same
|
|
417
|
+
`read_api` token `yad-verified-commits` already needs — or, without one, the job's own `CI_JOB_TOKEN`,
|
|
418
|
+
which GitLab's job-token access list allows on a single merge request (an older GitLab may not). It goes to `curl` in a header file, never on
|
|
419
|
+
its command line, and only to that GitLab's own API; `node` decodes the answer. If the full text
|
|
420
|
+
cannot be read (no token that works, no `curl` or `node`, no answer), the cut body is checked as
|
|
421
|
+
before and the note below also says why and to set `GITLAB_TOKEN`. A fork's pipeline runs in the fork
|
|
422
|
+
and cannot read the target project's merge request; its note says so, and only the order of the
|
|
423
|
+
sections helps there. The API answers with the description as it is now, so a job re-run after the
|
|
424
|
+
author edits a long description checks the edit (a short one is read from the pipeline's variable);
|
|
341
425
|
|
|
342
426
|
- the GitLab MR templates (`yad-pr-template` `templates/gitlab/…` and `templates/product/gitlab/…`) carry
|
|
343
427
|
the constraint as a comment and keep every required section early, so a truncated body still passes;
|
|
344
|
-
- when a required section is missing **and** the body it read
|
|
345
|
-
|
|
428
|
+
- when a required section is missing **and** the body it read was cut (GitLab's flag, or ≥ 2700
|
|
429
|
+
characters) and the full text could not be read, the gate prints a `NOTE` naming the truncation, why
|
|
430
|
+
the full text was not read and, only where a token change can help, what to change (no variable and a
|
|
431
|
+
refusal: set `GITLAB_TOKEN`, or in a fork, that a fork cannot read the target's MR; a variable that is
|
|
432
|
+
set: 401 renew or replace it, 403 give it `read_api`, 404 its user cannot see the project; a timeout, a
|
|
433
|
+
5xx or an odd answer: the reason alone), and the fix — reorder the required sections above the cutoff and push
|
|
346
434
|
the long narrative to the end. Never delete a section: reordering is always allowed.
|
|
347
435
|
|
|
348
436
|
## 8. Phase 6 — feature-thread gates (`lineage-check.sh`, `epic-open.sh`, `reconcile-debt-check.sh`)
|
|
@@ -353,7 +441,10 @@ resolve the owning epic the same way: `Task:` trailer → `specs/<story>/link.md
|
|
|
353
441
|
→ the Product epic. All **fail closed** on an unresolvable base; all are **per commit**; `ci|chore|build|test`
|
|
354
442
|
commits **with no `Task:` trailer** are exempt — like spec-link, the exemption waives the requirement
|
|
355
443
|
for an owning epic, never the validity of one that is claimed, so a maintenance subject cannot buy a
|
|
356
|
-
pass past the sealed-epic / orphan-thread / frozen-thread checks.
|
|
444
|
+
pass past the sealed-epic / orphan-thread / frozen-thread checks. The one deliberate exception is the
|
|
445
|
+
SHA exemption (§1): a commit listed in the base's `.sdlc/gate-exempt` skips all three gates, those checks
|
|
446
|
+
included, before anything else is judged — a reviewed waiver of one named commit, which no subject line
|
|
447
|
+
can buy. When the **Product is not reachable** from CI (the usual case for a code-repo
|
|
357
448
|
PR), each degrades to a **PASS-with-note** — the Product-side check (`yad doctor` / `yad reconcile`) covers
|
|
358
449
|
that path, and spec-link still proves the story link.
|
|
359
450
|
|
|
@@ -633,10 +724,13 @@ What it does in each case:
|
|
|
633
724
|
|
|
634
725
|
| Case | Result |
|
|
635
726
|
| --- | --- |
|
|
636
|
-
| No record on the base, no `
|
|
637
|
-
|
|
|
727
|
+
| No record on the base, no `git_url` in the record (or one written with a JSON escape, a quote or a backslash, which it cannot read: write it without escapes), or no `YAD_PRODUCT_TOKEN` on a PR from a fork (a fork is never given secrets) or outside CI | A note; nothing is cloned, and the gates defer as before. |
|
|
728
|
+
| No `YAD_PRODUCT_TOKEN` on a PR/MR that is **not** from a fork, while the base record names the Product (#345) | A `WARNING [product-checkout]` line (and a `::warning` annotation on GitHub); nothing is cloned and the gates defer — the job does not fail. On GitHub the workflow passes `YAD_PR_FORK` (head repo ≠ this repo); on GitLab the pipeline is a fork's when it runs outside the MR's target project (`CI_PROJECT_ID` ≠ `CI_MERGE_REQUEST_PROJECT_ID`) — a fork's MR pipeline a maintainer runs in the target project gets its variables, and warns. A Dependabot PR is told to add the token as a Dependabot secret too. |
|
|
729
|
+
| A token whose expiry the Product host reports within 30 days (#345) | A `WARNING` naming the date; the clone goes on. More than 30 days: a note with the date. |
|
|
730
|
+
| The host rejects the token on its API (HTTP 401) | If the clone then fails: **FAIL**, saying the token has expired or been revoked. If the clone works: a `WARNING`. |
|
|
731
|
+
| The record's `path` is outside the repo, `.`, absolute, or under `.git` | **FAIL** — CI can only check a second repo out inside the workspace. Change `path` in its own PR and merge that first (the record is read from the base; `yad check --fix` keeps a `path` that is set). An empty `path` is one `yad check --fix --push` from the Product writes, for each code repo cloned on that machine on its default branch. A path of only spaces fails too, and so does one written with a JSON escape, a quote or a backslash, which the gate cannot read: change that one. |
|
|
638
732
|
| A folder on the way to `path` is a symlink (one the PR tracks, say) | **FAIL** — git would clone through it, to wherever it points. |
|
|
639
|
-
| The `path` holds files this repo tracks | **FAIL** — the gates refuse a tracked Product path anyway. |
|
|
733
|
+
| The `path` holds files this repo tracks | **FAIL** — the gates refuse a tracked Product path anyway. Untrack the files if they do not belong in the repo (`git rm -r --cached --`, and add the folder to `.gitignore`), or change `path` in its own PR and merge that first. |
|
|
640
734
|
| The folder is already there | Left as it is. |
|
|
641
735
|
| The clone fails with a token set | **FAIL**, naming the URL and branch — a broken setup must not read like a deferral. |
|
|
642
736
|
|
|
@@ -644,6 +738,18 @@ The token is handed to git through its environment (`GIT_CONFIG_COUNT`, git 2.31
|
|
|
644
738
|
never on a command line or in a URL; on GitHub the encoded form is masked too. An `ssh` `git_url`
|
|
645
739
|
(`git@host:org/repo.git`) is cloned as the same repo over `https`.
|
|
646
740
|
|
|
741
|
+
**The token's expiry (#345).** Before the clone, the script makes one call to the Product host's API with
|
|
742
|
+
the token, handed to `curl` in a header file (`-H @file`), never on its command line, and only to the
|
|
743
|
+
Product's own host — or, for GitHub's cloud, its API host (`api.github.com`, `api.<sub>.ghe.com`). The API is chosen by that host first — `github.com` and `*.ghe.com` are GitHub, a host
|
|
744
|
+
with `gitlab` in its name is GitLab — and only for any other host by the CI it runs in. GitHub:
|
|
745
|
+
`rate_limit`, whose `github-authentication-token-expiration` response header carries a personal access
|
|
746
|
+
token's expiry. GitLab: `/api/v4/personal_access_tokens/self`, whose `expires_at` is the token's. A
|
|
747
|
+
token with only `read_repository` — the least it needs to clone — may not call GitLab's API at all
|
|
748
|
+
(HTTP 403); the note then points at `yad doctor`, which warns about the Product's **project** access
|
|
749
|
+
tokens that expire soon (not group or personal ones). A token with no expiry, an app token or no `curl` gives a note too, never a failure — only the clone
|
|
750
|
+
decides that. `yad doctor` checks where the token is SET (see
|
|
751
|
+
`docs/CLI.md`); it never sees the token itself.
|
|
752
|
+
|
|
647
753
|
## Sync with existing CI (merge, never clobber)
|
|
648
754
|
|
|
649
755
|
`wire` is **additive**: it brings the SDLC gates into a repo that may already have CI, without ever
|
|
@@ -903,6 +1009,12 @@ names can actually close:
|
|
|
903
1009
|
|
|
904
1010
|
## Running by hand (Phase 3 is manual)
|
|
905
1011
|
|
|
1012
|
+
`yad run checks` runs every installed gate in one go, the way CI runs them: this repo's own `checks/`,
|
|
1013
|
+
against `origin/<default branch>`, with the Product's default branch written where
|
|
1014
|
+
`.sdlc/product-link.json` says while the four Product-reading gates run, and removed after (a folder
|
|
1015
|
+
already there is read as it is and kept: a run removes only what it wrote). Signatures are checked with git there; the platform's
|
|
1016
|
+
Verified badge is judged in CI. To run one gate on its own:
|
|
1017
|
+
|
|
906
1018
|
From inside the code repo, against the PR/MR base (e.g. `master`). For the gates that take one, the
|
|
907
1019
|
base argument is optional — omit it and the gate resolves the trunk in the order above (configured
|
|
908
1020
|
`default_branch`, else `origin/HEAD`, else `origin/main`), printing the base it chose; pass it (or
|
|
@@ -18,10 +18,29 @@ package_manager="$(yad_detect_package_manager "$package_manager_spec")"
|
|
|
18
18
|
run_with_words="$(yad_package_manager_command "$package_manager_spec" "$package_manager")"
|
|
19
19
|
read -r -a run_with <<< "$run_with_words"
|
|
20
20
|
|
|
21
|
+
# One step of the gate. A failing step used to end the job under `set -e` with only the tool's own
|
|
22
|
+
# output; this names the step, the command to run by hand, and the missing-script case (#351).
|
|
23
|
+
run_step() {
|
|
24
|
+
local step="$1" has=0
|
|
25
|
+
shift
|
|
26
|
+
# Checked before it runs: npm prints nothing for a missing script, and runs an empty one as a pass,
|
|
27
|
+
# so an empty "test" would read as green. Exit 3 is "none"; a package.json node cannot read is left
|
|
28
|
+
# to the run itself, which reports it.
|
|
29
|
+
YAD_STEP="$step" node --input-type=module -e 'import fs from "node:fs"; const p=JSON.parse(fs.readFileSync("package.json", "utf8").replace(/^\uFEFF/, "")); const s=p.scripts?.[process.env.YAD_STEP]; process.exit(typeof s === "string" && s.trim() ? 0 : 3)' 2>/dev/null || has=$?
|
|
30
|
+
if [ "$has" = 3 ]; then
|
|
31
|
+
echo "FAIL [build/test/lint]: package.json has no \"${step}\" script, or an empty one — add one; the gate runs lint, build and test, in that order."
|
|
32
|
+
exit 1
|
|
33
|
+
fi
|
|
34
|
+
if ! "${run_with[@]}" run --silent "$step" "$@"; then
|
|
35
|
+
echo "FAIL [build/test/lint]: '${run_with_words} run ${step}' failed — the output above says why. Run it on your machine, fix what it reports, and push again."
|
|
36
|
+
exit 1
|
|
37
|
+
fi
|
|
38
|
+
}
|
|
39
|
+
|
|
21
40
|
echo "[build/test/lint] lint…"
|
|
22
|
-
|
|
41
|
+
run_step lint
|
|
23
42
|
echo "[build/test/lint] build…"
|
|
24
|
-
|
|
43
|
+
run_step build
|
|
25
44
|
|
|
26
45
|
# Worker cap: when YAD_TEST_MAX_WORKERS is set AND the repo's test script is jest/vitest (the
|
|
27
46
|
# runners that accept --maxWorkers), forward it to bound CI test concurrency. For any other runner
|
|
@@ -39,6 +58,6 @@ fi
|
|
|
39
58
|
echo "[build/test/lint] test…"
|
|
40
59
|
# Intentional word-splitting: $extra is empty, `-- --maxWorkers=N` (npm), or `--maxWorkers=N` (pnpm).
|
|
41
60
|
# shellcheck disable=SC2086
|
|
42
|
-
|
|
61
|
+
run_step test $extra
|
|
43
62
|
|
|
44
63
|
echo "PASS [build/test/lint]: lint, build, and tests all green."
|