You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: amend SEED-002 artefacts + document branch model in README
Post-deployment amendments after the sync-master workflow ran cleanly
on 2026-06-11:
CONTEXT.md — new ## Post-Execution Learnings section captures two
facts discovered during deployment without rewriting locked decisions:
- workflow_dispatch requires the workflow on the default branch;
sentinel tag was used for bootstrap instead
- production-sync Environment must allow tag patterns (not just
the dev branch) for tag-triggered runs to deploy
SUMMARY.md:
- Preconditions: Environment "Deployment branches and tags" now
explicitly lists dev branch + *@v* tag + v[0-9]* tag patterns
- Manual Next Steps: marked 6 deployment items complete; 3 pending
- Deviations: added #4 (sentinel-tag bootstrap) and #5 (Environment
tag-pattern fix) covering the discoveries
- Self-Check: added rows for first successful sync run
README.md — expanded the Contributing section into three:
- ## Branch model — rationale (plugin install ships whole repo),
table of dev/master roles, strip-list, keep-list, link to SEED-002
- ## Contributing — flow for contributors (PR against dev)
- ## Releases — maintainer flow (tag push triggers sync)
Both internal links point to dev branch refs since SEED-002 and
CLAUDE.md are stripped from master.
Co-Authored-By: Claude <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: .planning/quick/260607-w84-execute-seed-002-branch-based-minimal-st/260607-w84-CONTEXT.md
+22Lines changed: 22 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -102,3 +102,25 @@ The Phase 2 ruleset config (deferred but documented for SUMMARY.md follow-up):
102
102
- Auth model assessment & rejected alternatives: captured in transcript of quick task 260607-w84; full rationale to be summarised in `260607-w84-SUMMARY.md`
103
103
104
104
</canonical_refs>
105
+
106
+
<post_execution_learnings>
107
+
## Post-Execution Learnings
108
+
109
+
Two facts discovered during deployment (after the LOCKED decisions above) that shaped the actual rollout. Captured here for future maintainers; the original decisions remain unchanged.
110
+
111
+
### `workflow_dispatch` requires the workflow on the default branch
112
+
- The original bootstrap path in this CONTEXT said: *"For the initial workflow_dispatch sanity check: trigger manually once via `gh workflow run` after the workflow file lands on dev."*
113
+
- This does not work: `workflow_dispatch` requires the workflow file to exist on the **default branch**, regardless of the `--ref` passed. Tag-push events do not have this restriction (they use the workflow at the tagged commit).
114
+
-**Actual bootstrap path used:** sentinel tag `v0.0.0-bootstrap` pushed on `dev`. The tag-push fired the workflow from dev's copy; the workflow stripped and force-pushed master. The sentinel tag was deleted from origin and locally after the run succeeded.
115
+
-**Implication for future maintainers:** if the workflow file is ever re-deleted from master (e.g., accidentally) and the workflow stops being invocable via `workflow_dispatch`, the recovery path is another bootstrap tag, not a `gh workflow run`.
116
+
117
+
### `production-sync` Environment must allow tag patterns *and* dev branch
118
+
- The original Phase 4 instruction restricted Environment "Deployment branches and tags" to `dev` only — intended to block workflow_dispatch from non-dev branches.
119
+
- This rejected the tag-push bootstrap with: *"Tag '...' is not allowed to deploy to production-sync due to environment protection rules."*
120
+
-**Required allowlist for tag-push events to deploy:**
121
+
-`dev` (branch) — gates workflow_dispatch
122
+
-`*@v*` (tag pattern) — allows skill release tags to deploy
123
+
-`v[0-9]*` (tag pattern) — allows whole-repo release tags to deploy
124
+
-**Implication for future maintainers:** any new release-tag pattern added to the workflow's `on.push.tags` list must ALSO be added to the Environment's deployment-tag allowlist or runs are silently rejected.
Copy file name to clipboardExpand all lines: .planning/quick/260607-w84-execute-seed-002-branch-based-minimal-st/260607-w84-SUMMARY.md
+35-7Lines changed: 35 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -70,7 +70,11 @@ The workflow will fail (token error, or hang waiting for Environment approval) u
70
70
3.**Create `production-sync` Environment** (Settings → Environments → New environment) — required by REV-07:
71
71
- Name: `production-sync` (exact match — the workflow references this name)
72
72
- Required reviewers: org owners or named maintainers
73
-
- Deployment branches: restrict to `dev`
73
+
-**Deployment branches AND tags** (critical — both required):
74
+
- Branch: `dev` (allows workflow_dispatch)
75
+
- Tag: `*@v*` (allows skill release tag pushes)
76
+
- Tag: `v[0-9]*` (allows whole-repo release tag pushes)
77
+
- Without the tag patterns, tag-triggered runs are rejected with: *"Tag '...' is not allowed to deploy to production-sync due to environment protection rules"*. **Any new tag pattern added to the workflow's `on.push.tags` list must also be added here.**
74
78
- Without this Environment, the job will hang on first dispatch / never start. Configure before any workflow run.
75
79
76
80
4.**Tag protection rule** (Settings → Tags → Add rule) — defense in depth for REV-03:
@@ -85,12 +89,20 @@ The workflow will fail (token error, or hang waiting for Environment approval) u
85
89
86
90
## Manual Next Steps (Post-Setup)
87
91
88
-
1. Push dev branch: `git push -u origin dev`
89
-
2. Dry-run via workflow_dispatch: `gh workflow run sync-master.yml --ref dev`
PLAN.md's suggested check (`git diff --cached --quiet && git diff --quiet`) would always show changes after `git rm` (deletions are staged). Replaced with counting staged/unstaged file names (`wc -l` on `git diff --cached --name-only`) for accurate detection of the "nothing changed" case.
134
146
147
+
**4. [Deployment-time discovery] Bootstrap path changed from workflow_dispatch to sentinel tag**
148
+
149
+
PLAN.md and the deployment plan called for a `workflow_dispatch` dry-run as the first workflow execution. This failed with `HTTP 404: workflow sync-master.yml not found on the default branch`. Root cause: `workflow_dispatch` requires the workflow file to exist on the **default branch** (master), but our master didn't yet have it.
150
+
151
+
Tag-push events do NOT have this restriction — they use the workflow file at the tagged commit's ref. Bootstrap was performed by pushing sentinel tag `v0.0.0-bootstrap` on dev, which fired the workflow from dev's copy. The workflow stripped and force-pushed master, landing the workflow file on master in the process. From then on, `workflow_dispatch` works normally. The sentinel tag was deleted from origin and locally after the run succeeded.
152
+
153
+
This discovery is captured in CONTEXT.md `## Post-Execution Learnings` for future maintainers, and the affected Phase 4 (Environment config) step in `## Preconditions for First Sync Run` was updated to require tag patterns in the deployment-tag allowlist.
154
+
155
+
**5. [Deployment-time discovery] Environment must allow tag patterns explicitly**
156
+
157
+
Related to deviation #4. The `production-sync` Environment was initially configured per the plan with deployment-branches restricted to `dev` only. The sentinel-tag bootstrap was rejected with: *"Tag 'v0.0.0-bootstrap' is not allowed to deploy to production-sync due to environment protection rules"*.
158
+
159
+
Fix: added `*@v*` and `v[0-9]*` as tag rules in the Environment's "Deployment branches and tags" section. After the fix, the bootstrap succeeded on re-run.
160
+
135
161
## Self-Check
136
162
137
163
-[x]`.github/workflows/sync-master.yml` exists at correct path
Copy file name to clipboardExpand all lines: README.md
+44-6Lines changed: 44 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -54,14 +54,52 @@ npm test
54
54
55
55
Landing page: `npx serve .` then open `http://localhost:3000`.
56
56
57
-
## Contributing
57
+
## Branch model
58
+
59
+
This repo uses a two-branch model to keep end-user plugin installs lean.
60
+
61
+
**Why:**`claude plugin marketplace add` and `clawhub install` clone the entire git repository to user machines (twice — once for the marketplace mirror, once for the version-pinned cache). Everything committed ships to every user. Without this split, dozens of planning files, tests, and dev-only scripts would land in `~/.claude/plugins/...` on every install. There is no native `.claudeignore` / `files` field in the plugin spec at the time of writing, so the split is the cleanest way to scope what reaches consumers.
62
+
63
+
**How:**
64
+
65
+
| Branch | Role | What's on it |
66
+
|--------|------|--------------|
67
+
|`dev`| Source of truth — all human work, PRs, planning artefacts, tests, build tooling | Full repo |
68
+
|`master` (default) | Consumer-facing — what plugin installs and Netlify serve |`dev` minus the strip-list |
58
69
59
-
Development happens on the `dev` branch. `master` is a derived, consumer-facing branch regenerated automatically by a GitHub Action on release tag pushes — do not push to it directly.
**Keep-list** (present on both branches): `.claude-plugin/`, skill dirs, root `SKILL.md`, `index.html`, `netlify/`, `.well-known/`, `sitemap.xml`, `robots.txt`, favicons, `LICENSE`, `README.md`, `CHANGELOG.md`, `.github/workflows/`.
73
+
74
+
`master` is regenerated automatically by [`.github/workflows/sync-master.yml`](.github/workflows/sync-master.yml) on release-tag pushes. Direct human pushes to `master` are discouraged — the workflow will overwrite them on the next sync. Tag protection rules restrict who can create release tags; the sync workflow itself runs under a dedicated `kleros-skills-sync` GitHub App identity scoped to this repo.
75
+
76
+
For the full design rationale, security model, and rejected alternatives, see [SEED-002](https://github.com/kleros/kleros-skills/blob/dev/.planning/seeds/SEED-002-exclude-planning-from-plugin-install.md) on the `dev` branch.
77
+
78
+
## Contributing
60
79
61
-
1. Fork or branch from `dev`
62
-
2. Make changes, run `npm test`
63
-
3. PR against `dev`
64
-
4. On release tag push, the sync Action strips dev-only files and updates `master`
80
+
1. Branch from `dev` (or fork and branch from your fork's `dev`)
81
+
2. Make your changes
82
+
3. Run `npm test` locally
83
+
4. Open a PR targeting `dev` — never `master`
84
+
85
+
## Releases (maintainers)
86
+
87
+
1. Merge release-ready commits into `dev`
88
+
2. Bump the relevant version per the [Skill release pattern](https://github.com/kleros/kleros-skills/blob/dev/CLAUDE.md) (skill tags use `skillname@vX.Y.Z`; whole-repo tags use `vX.Y.Z`)
89
+
3. Tag and push:
90
+
```bash
91
+
git tag -a "kleros-curate@v1.0.1" -m "release notes here"
92
+
git push origin "kleros-curate@v1.0.1"
93
+
```
94
+
4. The sync Action runs:
95
+
-`npm test` (must pass)
96
+
-`npm run update-digests` freshness check (must pass)
97
+
- Strips dev-only files
98
+
- Sanity-checks the stripped tree (asserts strip-list absent and keep-list present)
99
+
- Force-pushes the result to `master` under the `kleros-skills-sync[bot]` identity
100
+
5.`master` redeploys to Netlify; the new release is live for plugin installs within minutes
101
+
102
+
If any gate fails, `master` stays at the previous good state — the tag exists but the release does not reach users until the issue is fixed and a new tag is pushed.
0 commit comments