@ikon85/agent-workflow-kit 0.34.4 → 0.34.6
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/.agents/skills/kit-release/SKILL.md +29 -21
- package/.agents/skills/kit-update/SKILL.md +6 -3
- package/.agents/skills/setup-workflow/SKILL.md +13 -5
- package/.agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml +1 -3
- package/.claude/skills/kit-release/SKILL.md +29 -21
- package/.claude/skills/kit-update/SKILL.md +6 -3
- package/.claude/skills/setup-workflow/SKILL.md +13 -5
- package/.claude/skills/setup-workflow/assets/agent-workflow-kit-update.yml +1 -3
- package/README.md +15 -0
- package/agent-workflow-kit.package.json +10 -10
- package/docs/adr/0001-consumer-divergence-policy.md +4 -0
- package/docs/adr/0003-kit-core-and-project-extension-lifecycle.md +63 -0
- package/docs/adr/0004-release-intent-is-a-version-tag.md +18 -5
- package/docs/agents/board-sync.md +1 -1
- package/docs/agents/workflow-capabilities.json +17 -0
- package/docs/research/benchlm-routing-source.md +198 -0
- package/docs/research/consumer-owned-protocol-files.md +238 -0
- package/docs/research/frontend-agent-benchmarks.md +282 -0
- package/docs/research/model-effort-routing-benchmarks.md +261 -0
- package/docs/research/provider-neutral-agent-routing.md +207 -0
- package/package.json +1 -1
- package/scripts/kit-release.test.mjs +10 -4
- package/scripts/kit-update-pr.mjs +1 -1
- package/scripts/kit-update-pr.test.mjs +2 -0
- package/scripts/test_release_authorization_contract.py +101 -0
- package/scripts/test_skill_readiness_contract.py +6 -1
- package/scripts/test_skill_setup_workflow_seeds.py +18 -17
- package/src/commands/update.mjs +52 -20
- package/src/lib/bundle.mjs +1 -1
- package/src/lib/updateCandidate.mjs +278 -50
- package/src/lib/verifyUpdateCandidate.mjs +220 -0
- package/src/lib/verifyUpdateCandidateArtifacts.mjs +78 -0
- package/src/lib/verifyUpdateCandidateProtocol.mjs +221 -0
- package/src/lib/verifyUpdateCandidateTransaction.mjs +152 -0
|
@@ -1,14 +1,18 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: kit-release
|
|
3
|
-
description: "Prepare and
|
|
3
|
+
description: "Prepare, integrate and publish a verified agent-workflow-kit release: one confirmed Semver authorizes the annotated version tag, then monitor npm/GitHub parity to released."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Kit Release
|
|
7
7
|
|
|
8
8
|
Prepare a release deterministically. This skill owns the shipped-delta decision,
|
|
9
|
-
metadata preparation, verification, and the
|
|
10
|
-
|
|
11
|
-
|
|
9
|
+
metadata preparation, verification, and the post-merge publication intent. It
|
|
10
|
+
delegates commit, branch push, PR, merge, and cleanup to wrapup. It never
|
|
11
|
+
publishes to a registry or creates a GitHub release by hand — it records intent
|
|
12
|
+
with the annotated tag and lets the trusted workflow publish.
|
|
13
|
+
|
|
14
|
+
The release has **one** human gate: the confirmed Semver in step 2. Everything
|
|
15
|
+
after it — merge, tag, publish, parity check — is the agent's to carry out.
|
|
12
16
|
|
|
13
17
|
## Workflow
|
|
14
18
|
|
|
@@ -33,8 +37,8 @@ never publishes to a registry or creates a GitHub release directly.
|
|
|
33
37
|
Do not turn a narrower build-only or single-action request into this
|
|
34
38
|
authority.
|
|
35
39
|
|
|
36
|
-
|
|
37
|
-
|
|
40
|
+
Either route authorizes exactly one target — and that authorization carries
|
|
41
|
+
through to its tag and publish. This is the release's single human gate.
|
|
38
42
|
|
|
39
43
|
3. Prepare that authorized exact version:
|
|
40
44
|
|
|
@@ -52,21 +56,25 @@ never publishes to a registry or creates a GitHub release directly.
|
|
|
52
56
|
`scripts/wrapup-land.py` exclusively own commit, push, PR creation, merge,
|
|
53
57
|
and cleanup. Do not reproduce those operations here.
|
|
54
58
|
|
|
55
|
-
5.
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
59
|
+
5. Publish. Merging integrates the prepared release; only the annotated tag
|
|
60
|
+
starts publication. Verify that the package version on current `origin/main`
|
|
61
|
+
is exactly `<version>`, then create and push the matching annotated
|
|
62
|
+
`v<version>` tag — **the confirmed Semver authorizes the whole release,
|
|
63
|
+
through tag and publish, so do this without asking again**. The target was
|
|
64
|
+
chosen once, at step 2; nothing between there and here produces information
|
|
65
|
+
a second gate could act on. Report the integrated commit as you tag it, not
|
|
66
|
+
as a question.
|
|
67
|
+
|
|
68
|
+
Publication is **irreversible** — npm versions cannot be reused, and the
|
|
69
|
+
unpublish window is narrow and breaks consumers. The safety lives in gates
|
|
70
|
+
that already ran, not in a prompt: `release:guard`, `kit:staleness`, the full
|
|
71
|
+
suite and `npm pack --dry-run` before merge, then the workflow's own tag
|
|
72
|
+
identity, package version, main ancestry and artifact checks after it. A
|
|
73
|
+
lightweight tag, a mismatching version, or a commit outside canonical `main`
|
|
74
|
+
is invalid release intent. Never infer a tag target, move an existing tag, or
|
|
75
|
+
tag an unmerged commit.
|
|
76
|
+
|
|
77
|
+
6. Monitor the tag-triggered `release.yml` workflow and inspect its externally
|
|
70
78
|
reconstructable state:
|
|
71
79
|
|
|
72
80
|
```sh
|
|
@@ -30,9 +30,12 @@ release contain the same artifact.
|
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
The command checks npm/GitHub release parity before staging. It prepares a
|
|
33
|
-
complete candidate outside the
|
|
34
|
-
|
|
35
|
-
|
|
33
|
+
complete manifest-bounded candidate outside the Consumer, verifies the
|
|
34
|
+
Kit-owned manifest, artifact, protocol, schema/reference, syntax, and
|
|
35
|
+
transaction invariants, and activates only that verified candidate. It
|
|
36
|
+
never runs a Consumer package script, configurable verification command, or
|
|
37
|
+
legacy fallback. A staging or verification failure leaves the installed
|
|
38
|
+
tree byte-identical.
|
|
36
39
|
|
|
37
40
|
The staged candidate also adopts the current readiness schema without
|
|
38
41
|
invoking `setup-workflow`: it preserves explicit readiness decisions and
|
|
@@ -81,11 +81,19 @@ Seed `docs/agents/issue-tracker.md` from the matching template in this folder: [
|
|
|
81
81
|
|
|
82
82
|
### 2a. Automatic Kit update pull requests (GitHub tracker only)
|
|
83
83
|
|
|
84
|
-
> A short scheduled check can keep the installed Kit current by opening one
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
84
|
+
> A short scheduled check can keep the installed Kit current by opening one
|
|
85
|
+
> normal pull request after the candidate passes the built-in Kit invariant
|
|
86
|
+
> validator. It runs no Consumer package script and never merges the pull
|
|
87
|
+
> request for you.
|
|
88
|
+
|
|
89
|
+
Only after the user has confirmed a **GitHub tracker**, ask in plain language:
|
|
90
|
+
*"Should GitHub check weekly for a verified Agent Workflow Kit update and keep
|
|
91
|
+
one update pull request ready?"* Offer these explicit choices:
|
|
92
|
+
|
|
93
|
+
Before offering **Enable**, explain that the update command uses the same
|
|
94
|
+
built-in Kit invariant validator as manual and agent-driven updates. There is
|
|
95
|
+
no Consumer package script, lockfile, configurable verification profile, or
|
|
96
|
+
legacy test fallback prerequisite.
|
|
89
97
|
|
|
90
98
|
Also read the repository Actions policy before enabling:
|
|
91
99
|
|
|
@@ -23,9 +23,7 @@ jobs:
|
|
|
23
23
|
- uses: actions/setup-node@v4
|
|
24
24
|
with:
|
|
25
25
|
node-version: 22.14
|
|
26
|
-
- name:
|
|
27
|
-
run: npm ci --ignore-scripts
|
|
28
|
-
- name: Verify, test, and upsert the Kit update pull request
|
|
26
|
+
- name: Verify and upsert the Kit update pull request
|
|
29
27
|
env:
|
|
30
28
|
GH_TOKEN: ${{ github.token }}
|
|
31
29
|
run: npx --yes --package=@ikon85/agent-workflow-kit@latest agent-workflow-kit-update-pr
|
|
@@ -1,14 +1,18 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: kit-release
|
|
3
|
-
description: "Prepare and
|
|
3
|
+
description: "Prepare, integrate and publish a verified agent-workflow-kit release: one confirmed Semver authorizes the annotated version tag, then monitor npm/GitHub parity to released."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Kit Release
|
|
7
7
|
|
|
8
8
|
Prepare a release deterministically. This skill owns the shipped-delta decision,
|
|
9
|
-
metadata preparation, verification, and the
|
|
10
|
-
|
|
11
|
-
|
|
9
|
+
metadata preparation, verification, and the post-merge publication intent. It
|
|
10
|
+
delegates commit, branch push, PR, merge, and cleanup to wrapup. It never
|
|
11
|
+
publishes to a registry or creates a GitHub release by hand — it records intent
|
|
12
|
+
with the annotated tag and lets the trusted workflow publish.
|
|
13
|
+
|
|
14
|
+
The release has **one** human gate: the confirmed Semver in step 2. Everything
|
|
15
|
+
after it — merge, tag, publish, parity check — is the agent's to carry out.
|
|
12
16
|
|
|
13
17
|
## Workflow
|
|
14
18
|
|
|
@@ -33,8 +37,8 @@ never publishes to a registry or creates a GitHub release directly.
|
|
|
33
37
|
Do not turn a narrower build-only or single-action request into this
|
|
34
38
|
authority.
|
|
35
39
|
|
|
36
|
-
|
|
37
|
-
|
|
40
|
+
Either route authorizes exactly one target — and that authorization carries
|
|
41
|
+
through to its tag and publish. This is the release's single human gate.
|
|
38
42
|
|
|
39
43
|
3. Prepare that authorized exact version:
|
|
40
44
|
|
|
@@ -52,21 +56,25 @@ never publishes to a registry or creates a GitHub release directly.
|
|
|
52
56
|
`scripts/wrapup-land.py` exclusively own commit, push, PR creation, merge,
|
|
53
57
|
and cleanup. Do not reproduce those operations here.
|
|
54
58
|
|
|
55
|
-
5.
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
59
|
+
5. Publish. Merging integrates the prepared release; only the annotated tag
|
|
60
|
+
starts publication. Verify that the package version on current `origin/main`
|
|
61
|
+
is exactly `<version>`, then create and push the matching annotated
|
|
62
|
+
`v<version>` tag — **the confirmed Semver authorizes the whole release,
|
|
63
|
+
through tag and publish, so do this without asking again**. The target was
|
|
64
|
+
chosen once, at step 2; nothing between there and here produces information
|
|
65
|
+
a second gate could act on. Report the integrated commit as you tag it, not
|
|
66
|
+
as a question.
|
|
67
|
+
|
|
68
|
+
Publication is **irreversible** — npm versions cannot be reused, and the
|
|
69
|
+
unpublish window is narrow and breaks consumers. The safety lives in gates
|
|
70
|
+
that already ran, not in a prompt: `release:guard`, `kit:staleness`, the full
|
|
71
|
+
suite and `npm pack --dry-run` before merge, then the workflow's own tag
|
|
72
|
+
identity, package version, main ancestry and artifact checks after it. A
|
|
73
|
+
lightweight tag, a mismatching version, or a commit outside canonical `main`
|
|
74
|
+
is invalid release intent. Never infer a tag target, move an existing tag, or
|
|
75
|
+
tag an unmerged commit.
|
|
76
|
+
|
|
77
|
+
6. Monitor the tag-triggered `release.yml` workflow and inspect its externally
|
|
70
78
|
reconstructable state:
|
|
71
79
|
|
|
72
80
|
```sh
|
|
@@ -30,9 +30,12 @@ release contain the same artifact.
|
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
The command checks npm/GitHub release parity before staging. It prepares a
|
|
33
|
-
complete candidate outside the
|
|
34
|
-
|
|
35
|
-
|
|
33
|
+
complete manifest-bounded candidate outside the Consumer, verifies the
|
|
34
|
+
Kit-owned manifest, artifact, protocol, schema/reference, syntax, and
|
|
35
|
+
transaction invariants, and activates only that verified candidate. It
|
|
36
|
+
never runs a Consumer package script, configurable verification command, or
|
|
37
|
+
legacy fallback. A staging or verification failure leaves the installed
|
|
38
|
+
tree byte-identical.
|
|
36
39
|
|
|
37
40
|
The staged candidate also adopts the current readiness schema without
|
|
38
41
|
invoking `setup-workflow`: it preserves explicit readiness decisions and
|
|
@@ -81,11 +81,19 @@ Seed `docs/agents/issue-tracker.md` from the matching template in this folder: [
|
|
|
81
81
|
|
|
82
82
|
### 2a. Automatic Kit update pull requests (GitHub tracker only)
|
|
83
83
|
|
|
84
|
-
> A short scheduled check can keep the installed Kit current by opening one
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
84
|
+
> A short scheduled check can keep the installed Kit current by opening one
|
|
85
|
+
> normal pull request after the candidate passes the built-in Kit invariant
|
|
86
|
+
> validator. It runs no Consumer package script and never merges the pull
|
|
87
|
+
> request for you.
|
|
88
|
+
|
|
89
|
+
Only after the user has confirmed a **GitHub tracker**, ask in plain language:
|
|
90
|
+
*"Should GitHub check weekly for a verified Agent Workflow Kit update and keep
|
|
91
|
+
one update pull request ready?"* Offer these explicit choices:
|
|
92
|
+
|
|
93
|
+
Before offering **Enable**, explain that the update command uses the same
|
|
94
|
+
built-in Kit invariant validator as manual and agent-driven updates. There is
|
|
95
|
+
no Consumer package script, lockfile, configurable verification profile, or
|
|
96
|
+
legacy test fallback prerequisite.
|
|
89
97
|
|
|
90
98
|
Also read the repository Actions policy before enabling:
|
|
91
99
|
|
|
@@ -23,9 +23,7 @@ jobs:
|
|
|
23
23
|
- uses: actions/setup-node@v4
|
|
24
24
|
with:
|
|
25
25
|
node-version: 22.14
|
|
26
|
-
- name:
|
|
27
|
-
run: npm ci --ignore-scripts
|
|
28
|
-
- name: Verify, test, and upsert the Kit update pull request
|
|
26
|
+
- name: Verify and upsert the Kit update pull request
|
|
29
27
|
env:
|
|
30
28
|
GH_TOKEN: ${{ github.token }}
|
|
31
29
|
run: npx --yes --package=@ikon85/agent-workflow-kit@latest agent-workflow-kit-update-pr
|
package/README.md
CHANGED
|
@@ -387,6 +387,21 @@ the old way. Decision record:
|
|
|
387
387
|
|
|
388
388
|
## Release notes
|
|
389
389
|
|
|
390
|
+
### 0.34.6
|
|
391
|
+
|
|
392
|
+
- changed: `.agents/skills/kit-release/SKILL.md`
|
|
393
|
+
- changed: `.claude/skills/kit-release/SKILL.md`
|
|
394
|
+
|
|
395
|
+
### 0.34.5
|
|
396
|
+
|
|
397
|
+
- changed: `.agents/skills/kit-update/SKILL.md`
|
|
398
|
+
- changed: `.agents/skills/setup-workflow/SKILL.md`
|
|
399
|
+
- changed: `.agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml`
|
|
400
|
+
- changed: `.claude/skills/kit-update/SKILL.md`
|
|
401
|
+
- changed: `.claude/skills/setup-workflow/SKILL.md`
|
|
402
|
+
- changed: `.claude/skills/setup-workflow/assets/agent-workflow-kit-update.yml`
|
|
403
|
+
- changed: `scripts/kit-update-pr.mjs`
|
|
404
|
+
|
|
390
405
|
### 0.34.4
|
|
391
406
|
|
|
392
407
|
- changed: `.agents/skills/kit-release/SKILL.md`
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
{
|
|
2
|
-
"kitVersion": "0.34.
|
|
2
|
+
"kitVersion": "0.34.6",
|
|
3
3
|
"files": [
|
|
4
4
|
{
|
|
5
5
|
"path": ".agents/skills/ask-matt/SKILL.md",
|
|
@@ -367,7 +367,7 @@
|
|
|
367
367
|
"ownerSkill": "kit-release",
|
|
368
368
|
"surface": "codex",
|
|
369
369
|
"installRole": "maintainer",
|
|
370
|
-
"sha256": "
|
|
370
|
+
"sha256": "38a3df1f9d4b5573180dc67daba85eb3fd143ae3b60ca6dbfed3297d6a0855cd",
|
|
371
371
|
"mode": 420,
|
|
372
372
|
"origin": "kit"
|
|
373
373
|
},
|
|
@@ -377,7 +377,7 @@
|
|
|
377
377
|
"ownerSkill": "kit-update",
|
|
378
378
|
"surface": "codex",
|
|
379
379
|
"installRole": "consumer",
|
|
380
|
-
"sha256": "
|
|
380
|
+
"sha256": "9129e14b12b573546e253e14be3b7793afe2ca2b46102bb7b5f2ec1a8276a1ec",
|
|
381
381
|
"mode": 420,
|
|
382
382
|
"origin": "kit"
|
|
383
383
|
},
|
|
@@ -577,7 +577,7 @@
|
|
|
577
577
|
"ownerSkill": "setup-workflow",
|
|
578
578
|
"surface": "codex",
|
|
579
579
|
"installRole": "consumer",
|
|
580
|
-
"sha256": "
|
|
580
|
+
"sha256": "dcabda3d93b7c79f35065a9f3130807ff29737e15187a68fdbc37533015d461d",
|
|
581
581
|
"mode": 420,
|
|
582
582
|
"origin": "kit"
|
|
583
583
|
},
|
|
@@ -677,7 +677,7 @@
|
|
|
677
677
|
"ownerSkill": "setup-workflow",
|
|
678
678
|
"surface": "codex",
|
|
679
679
|
"installRole": "consumer",
|
|
680
|
-
"sha256": "
|
|
680
|
+
"sha256": "0f098f6efeda6682726d918135f0a66ffbf9c90616293fd3833d5fe47fc5c927",
|
|
681
681
|
"mode": 420,
|
|
682
682
|
"origin": "kit"
|
|
683
683
|
},
|
|
@@ -1679,7 +1679,7 @@
|
|
|
1679
1679
|
"ownerSkill": "kit-release",
|
|
1680
1680
|
"surface": "claude",
|
|
1681
1681
|
"installRole": "maintainer",
|
|
1682
|
-
"sha256": "
|
|
1682
|
+
"sha256": "38a3df1f9d4b5573180dc67daba85eb3fd143ae3b60ca6dbfed3297d6a0855cd",
|
|
1683
1683
|
"mode": 420,
|
|
1684
1684
|
"origin": "kit"
|
|
1685
1685
|
},
|
|
@@ -1689,7 +1689,7 @@
|
|
|
1689
1689
|
"ownerSkill": "kit-update",
|
|
1690
1690
|
"surface": "claude",
|
|
1691
1691
|
"installRole": "consumer",
|
|
1692
|
-
"sha256": "
|
|
1692
|
+
"sha256": "9129e14b12b573546e253e14be3b7793afe2ca2b46102bb7b5f2ec1a8276a1ec",
|
|
1693
1693
|
"mode": 420,
|
|
1694
1694
|
"origin": "kit"
|
|
1695
1695
|
},
|
|
@@ -1909,7 +1909,7 @@
|
|
|
1909
1909
|
"ownerSkill": "setup-workflow",
|
|
1910
1910
|
"surface": "claude",
|
|
1911
1911
|
"installRole": "consumer",
|
|
1912
|
-
"sha256": "
|
|
1912
|
+
"sha256": "dcabda3d93b7c79f35065a9f3130807ff29737e15187a68fdbc37533015d461d",
|
|
1913
1913
|
"mode": 420,
|
|
1914
1914
|
"origin": "kit"
|
|
1915
1915
|
},
|
|
@@ -2009,7 +2009,7 @@
|
|
|
2009
2009
|
"ownerSkill": "setup-workflow",
|
|
2010
2010
|
"surface": "claude",
|
|
2011
2011
|
"installRole": "consumer",
|
|
2012
|
-
"sha256": "
|
|
2012
|
+
"sha256": "0f098f6efeda6682726d918135f0a66ffbf9c90616293fd3833d5fe47fc5c927",
|
|
2013
2013
|
"mode": 420,
|
|
2014
2014
|
"origin": "kit"
|
|
2015
2015
|
},
|
|
@@ -2535,7 +2535,7 @@
|
|
|
2535
2535
|
"path": "scripts/kit-update-pr.mjs",
|
|
2536
2536
|
"kind": "script",
|
|
2537
2537
|
"installRole": "consumer",
|
|
2538
|
-
"sha256": "
|
|
2538
|
+
"sha256": "c28bbd5a45583a92eca12758c1d626e04bce820300178b54933340759d1690fd",
|
|
2539
2539
|
"mode": 493,
|
|
2540
2540
|
"origin": "kit"
|
|
2541
2541
|
},
|
|
@@ -2,6 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
Status: accepted (2026-07-18, issue #130)
|
|
4
4
|
|
|
5
|
+
Partially superseded by ADR-0003: consumer ownership remains valid for genuine
|
|
6
|
+
project files, but no longer applies to Kit Core or to mixed core/extension
|
|
7
|
+
registries.
|
|
8
|
+
|
|
5
9
|
Since the consumer-source cutover the kit is SSOT for shipped files, but
|
|
6
10
|
consumers keep learning: edits made directly on a shipped file in a consumer
|
|
7
11
|
silently fork it, and every subsequent `kit-update` reports a permanent
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Kit Core and project extensions have separate identities
|
|
2
|
+
|
|
3
|
+
Status: accepted (2026-07-22, issues #190, #194, #196, #197)
|
|
4
|
+
|
|
5
|
+
The original divergence policy allowed any shipped path to become
|
|
6
|
+
consumer-owned. That is safe for a genuinely project-specific file, but not for
|
|
7
|
+
a protocol authority such as the skill/readiness registry: once a consumer
|
|
8
|
+
owns that mixed file, new Kit declarations stop arriving while local additions
|
|
9
|
+
and stale Kit declarations remain indistinguishable. A real consumer exhibited
|
|
10
|
+
exactly this state: the installed readiness harness was current while its owned
|
|
11
|
+
registry had no readiness capabilities or declarations.
|
|
12
|
+
|
|
13
|
+
We decided to model four explicit lifecycle states instead of treating every
|
|
14
|
+
local difference as file ownership:
|
|
15
|
+
|
|
16
|
+
1. **Kit Core** remains upstream-owned under the Kit's canonical identity. A
|
|
17
|
+
consumer cannot permanently own it under that same identity.
|
|
18
|
+
2. **Project extensions** live on separate consumer-owned surfaces. Every
|
|
19
|
+
shipped skill may load its optional `docs/agents/skills/<skill>.md`; local
|
|
20
|
+
skill identities live in a separate local registry. Neither surface changes
|
|
21
|
+
the corresponding Kit Core.
|
|
22
|
+
3. A **Contribution bridge** may temporarily retain a registered local Core
|
|
23
|
+
experiment. It must resolve into a project extension, a generalized upstream
|
|
24
|
+
contribution that returns in a release, or an explicit fork.
|
|
25
|
+
4. An **Explicit fork** has its own identity, version, and update line. Semantic
|
|
26
|
+
divergence cannot masquerade indefinitely as the canonical Kit skill.
|
|
27
|
+
|
|
28
|
+
An update composes and validates the complete protocol group in an isolated,
|
|
29
|
+
manifest-derived staged candidate. It never infers an ownership decision from
|
|
30
|
+
`--yes`: an unclassified collision blocks unchanged until a user classifies it.
|
|
31
|
+
Existing mixed states migrate semantically, preserving local identities and
|
|
32
|
+
project metadata on their new surfaces; an ambiguous semantic change blocks
|
|
33
|
+
instead of being overwritten or frozen silently.
|
|
34
|
+
|
|
35
|
+
The upstream route is capability-based, not maintainer-specific. At the moment
|
|
36
|
+
of contribution, repository permissions and an optional machine-local upstream
|
|
37
|
+
checkout determine whether the approved route can use a direct pull request, a
|
|
38
|
+
fork, or an issue. No consumer asks who the user is, and no telemetry reports
|
|
39
|
+
local edits automatically.
|
|
40
|
+
|
|
41
|
+
## Considered options
|
|
42
|
+
|
|
43
|
+
- **Keep arbitrary consumer-owned shipped paths:** rejected because a protocol
|
|
44
|
+
authority then stops receiving schema and behavior evolution under the same
|
|
45
|
+
identity.
|
|
46
|
+
- **Add more merge rules to the mixed registry:** rejected because local skills,
|
|
47
|
+
project annotations, readiness declarations, and upstream skill definitions
|
|
48
|
+
have different ownership and lifecycle semantics.
|
|
49
|
+
- **Overwrite Core and discard local changes:** rejected because it loses valid
|
|
50
|
+
project behavior and can destroy unregistered work.
|
|
51
|
+
- **Special-case the maintainer:** rejected because identity is irrelevant; the
|
|
52
|
+
portable distinction is whether the user has an approved route and the
|
|
53
|
+
required repository capabilities.
|
|
54
|
+
|
|
55
|
+
## Consequences
|
|
56
|
+
|
|
57
|
+
- ADR-0001 remains valid for genuine consumer-owned files but is narrowed for
|
|
58
|
+
Kit Core and mixed registries.
|
|
59
|
+
- Core updates can advance without erasing project-specific behavior.
|
|
60
|
+
- Consumers gain explicit extension, contribution, and fork lifecycles instead
|
|
61
|
+
of permanent accidental divergence.
|
|
62
|
+
- Migration requires a one-time semantic classification of existing mixed
|
|
63
|
+
states and must fail closed when that classification is ambiguous.
|
|
@@ -6,6 +6,17 @@ Clarified 2026-07-25 by issue #239: an explicit AFK end-to-end mandate may
|
|
|
6
6
|
authorize deterministic reversible release preparation, but never the
|
|
7
7
|
publication tag itself.
|
|
8
8
|
|
|
9
|
+
Amended 2026-07-25 by issue #257: the confirmed Semver authorizes the whole
|
|
10
|
+
release, through tag and publish. The separation of integration and publication
|
|
11
|
+
below is unchanged — merging still cannot publish, and only an annotated tag
|
|
12
|
+
records release intent — but that intent no longer waits for a second human
|
|
13
|
+
confirmation. The maintainer chooses the version once; the agent then merges,
|
|
14
|
+
tags, and monitors to `released`. The second gate had proven worse than no gate:
|
|
15
|
+
it left prepared versions sitting in `awaiting-tag` until someone returned,
|
|
16
|
+
which is how 0.34.2 was skipped and buried under 0.34.3 (#243). Safety stays in
|
|
17
|
+
the gates that run regardless of who is watching — guard, staleness, suite,
|
|
18
|
+
pack, and the workflow's own tag/version/ancestry validation.
|
|
19
|
+
|
|
9
20
|
The release workflow currently publishes whenever a merge to `main` changes
|
|
10
21
|
`package.json`. That keeps the canonical branch and npm close together, but it
|
|
11
22
|
also makes an ordinary merge an irreversible public action whose consequence is
|
|
@@ -39,11 +50,13 @@ We decided that integration and publication are separate transitions:
|
|
|
39
50
|
|
|
40
51
|
## Consequences
|
|
41
52
|
|
|
42
|
-
- A prepared version
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
53
|
+
- A prepared version exists on `main` in an `awaiting-tag` state only for as
|
|
54
|
+
long as the agent needs to tag it — not until a human returns (amended by
|
|
55
|
+
#257).
|
|
56
|
+
- The authorizing act is the confirmed Semver. An explicit AFK Wave/Program
|
|
57
|
+
mandate that names release preparation carries the same weight, and either
|
|
58
|
+
route reaches through tag and publish for that one target. A narrower
|
|
59
|
+
build-only or single-action request never becomes this authority.
|
|
47
60
|
- A single-Wave mandate does not authorize the next Program Wave. A later
|
|
48
61
|
explicit whole-Program mandate does authorize all planned Waves and remains in
|
|
49
62
|
force across their boundaries.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
{
|
|
2
|
+
"worktreeLifecycle": {
|
|
3
|
+
"enabled": true,
|
|
4
|
+
"worktreeRoot": ".worktrees",
|
|
5
|
+
"branchTemplate": "{type}/{issue}-{slug}",
|
|
6
|
+
"pathTemplate": "{issue}-{slug}",
|
|
7
|
+
"branchRegex": "^(?:feat|fix|chore|docs)/(?P<issue>\\d+)-",
|
|
8
|
+
"mainBranches": ["main"],
|
|
9
|
+
"protectedBranches": ["main"],
|
|
10
|
+
"setupEntry": "python3 scripts/worktree-lifecycle/setup.py",
|
|
11
|
+
"setupSteps": [],
|
|
12
|
+
"riskyCommandPatterns": [
|
|
13
|
+
"\\b(?:npm|pnpm|yarn)\\s+(?:run\\s+)?(?:test|typecheck|build)\\b",
|
|
14
|
+
"\\bgit\\s+(?:commit|push)\\b"
|
|
15
|
+
]
|
|
16
|
+
}
|
|
17
|
+
}
|