@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.
Files changed (34) hide show
  1. package/.agents/skills/kit-release/SKILL.md +29 -21
  2. package/.agents/skills/kit-update/SKILL.md +6 -3
  3. package/.agents/skills/setup-workflow/SKILL.md +13 -5
  4. package/.agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml +1 -3
  5. package/.claude/skills/kit-release/SKILL.md +29 -21
  6. package/.claude/skills/kit-update/SKILL.md +6 -3
  7. package/.claude/skills/setup-workflow/SKILL.md +13 -5
  8. package/.claude/skills/setup-workflow/assets/agent-workflow-kit-update.yml +1 -3
  9. package/README.md +15 -0
  10. package/agent-workflow-kit.package.json +10 -10
  11. package/docs/adr/0001-consumer-divergence-policy.md +4 -0
  12. package/docs/adr/0003-kit-core-and-project-extension-lifecycle.md +63 -0
  13. package/docs/adr/0004-release-intent-is-a-version-tag.md +18 -5
  14. package/docs/agents/board-sync.md +1 -1
  15. package/docs/agents/workflow-capabilities.json +17 -0
  16. package/docs/research/benchlm-routing-source.md +198 -0
  17. package/docs/research/consumer-owned-protocol-files.md +238 -0
  18. package/docs/research/frontend-agent-benchmarks.md +282 -0
  19. package/docs/research/model-effort-routing-benchmarks.md +261 -0
  20. package/docs/research/provider-neutral-agent-routing.md +207 -0
  21. package/package.json +1 -1
  22. package/scripts/kit-release.test.mjs +10 -4
  23. package/scripts/kit-update-pr.mjs +1 -1
  24. package/scripts/kit-update-pr.test.mjs +2 -0
  25. package/scripts/test_release_authorization_contract.py +101 -0
  26. package/scripts/test_skill_readiness_contract.py +6 -1
  27. package/scripts/test_skill_setup_workflow_seeds.py +18 -17
  28. package/src/commands/update.mjs +52 -20
  29. package/src/lib/bundle.mjs +1 -1
  30. package/src/lib/updateCandidate.mjs +278 -50
  31. package/src/lib/verifyUpdateCandidate.mjs +220 -0
  32. package/src/lib/verifyUpdateCandidateArtifacts.mjs +78 -0
  33. package/src/lib/verifyUpdateCandidateProtocol.mjs +221 -0
  34. package/src/lib/verifyUpdateCandidateTransaction.mjs +152 -0
@@ -1,14 +1,18 @@
1
1
  ---
2
2
  name: kit-release
3
- description: "Prepare and integrate a verified agent-workflow-kit release, then record separately confirmed publication intent with an annotated version tag and monitor npm/GitHub parity."
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 separate post-merge publication
10
- gate. It delegates commit, branch push, PR, merge, and cleanup to wrapup. It
11
- never publishes to a registry or creates a GitHub release directly.
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
- Both routes authorize one prepared target only. Neither authorizes
37
- publication.
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. After merge, report the exact integrated version and commit as
56
- `awaiting-tag`. Merging integrates the prepared release; it cannot start
57
- publication. Creating and pushing the annotated `v<version>` tag requires a
58
- **separate explicit confirmation** to publish that exact version. The
59
- earlier Semver confirmation or AFK preparation mandate authorized metadata
60
- preparation, not publication.
61
-
62
- 6. After that confirmation, verify that the package version on current
63
- `origin/main` is exactly `<version>`. Create a matching annotated
64
- `v<version>` tag on that commit and push only that tag. A lightweight tag,
65
- mismatching version, or commit outside canonical `main` is invalid release
66
- intent. Never infer a tag target, move an existing tag, or tag an unmerged
67
- commit.
68
-
69
- 7. Monitor the tag-triggered `release.yml` workflow and inspect its externally
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 consumer, runs the consumer's existing
34
- `npm test` command there, and activates only a verified candidate. A staging
35
- or verification failure leaves the installed tree byte-identical.
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 normal pull request after the candidate passes the consumer's own tests. It never merges the pull request for you.
85
-
86
- Only after the user has confirmed a **GitHub tracker**, ask in plain language: *"Should GitHub check weekly for a tested Agent Workflow Kit update and keep one update pull request ready?"* Offer these explicit choices:
87
-
88
- Before offering **Enable**, confirm the consumer has a committed `package-lock.json` and a usable `package.json` `npm test` command. The shipped workflow installs the locked dependencies with `npm ci --ignore-scripts`; without that lockfile/test contract it cannot prove the candidate in a clean checkout, so explain the prerequisite and do not create the workflow yet.
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: Install locked consumer dependencies
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 integrate a verified agent-workflow-kit release, then record separately confirmed publication intent with an annotated version tag and monitor npm/GitHub parity."
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 separate post-merge publication
10
- gate. It delegates commit, branch push, PR, merge, and cleanup to wrapup. It
11
- never publishes to a registry or creates a GitHub release directly.
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
- Both routes authorize one prepared target only. Neither authorizes
37
- publication.
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. After merge, report the exact integrated version and commit as
56
- `awaiting-tag`. Merging integrates the prepared release; it cannot start
57
- publication. Creating and pushing the annotated `v<version>` tag requires a
58
- **separate explicit confirmation** to publish that exact version. The
59
- earlier Semver confirmation or AFK preparation mandate authorized metadata
60
- preparation, not publication.
61
-
62
- 6. After that confirmation, verify that the package version on current
63
- `origin/main` is exactly `<version>`. Create a matching annotated
64
- `v<version>` tag on that commit and push only that tag. A lightweight tag,
65
- mismatching version, or commit outside canonical `main` is invalid release
66
- intent. Never infer a tag target, move an existing tag, or tag an unmerged
67
- commit.
68
-
69
- 7. Monitor the tag-triggered `release.yml` workflow and inspect its externally
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 consumer, runs the consumer's existing
34
- `npm test` command there, and activates only a verified candidate. A staging
35
- or verification failure leaves the installed tree byte-identical.
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 normal pull request after the candidate passes the consumer's own tests. It never merges the pull request for you.
85
-
86
- Only after the user has confirmed a **GitHub tracker**, ask in plain language: *"Should GitHub check weekly for a tested Agent Workflow Kit update and keep one update pull request ready?"* Offer these explicit choices:
87
-
88
- Before offering **Enable**, confirm the consumer has a committed `package-lock.json` and a usable `package.json` `npm test` command. The shipped workflow installs the locked dependencies with `npm ci --ignore-scripts`; without that lockfile/test contract it cannot prove the candidate in a clean checkout, so explain the prerequisite and do not create the workflow yet.
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: Install locked consumer dependencies
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.4",
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": "f584caa1753ed34de584418a4176015cc3e2382db06efae488bb6d785eab71b7",
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": "c3487295864d1d8d765e1c453c80daf77d3f08a2b0017f614e44e85170913624",
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": "d8abf995d67184b4459b9565c9062319fc42e8a685042b288b3066a07a6fda59",
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": "7281bb67588328aa4a788cbefe69f396c4617569335ce47cfb45bb5607d3205e",
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": "f584caa1753ed34de584418a4176015cc3e2382db06efae488bb6d785eab71b7",
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": "c3487295864d1d8d765e1c453c80daf77d3f08a2b0017f614e44e85170913624",
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": "d8abf995d67184b4459b9565c9062319fc42e8a685042b288b3066a07a6fda59",
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": "7281bb67588328aa4a788cbefe69f396c4617569335ce47cfb45bb5607d3205e",
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": "83f30a4ca938171cfa2f4153917813fae40bf2a906940e047c7066d18284209b",
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 may temporarily exist on `main` in an `awaiting-tag` state.
43
- - An explicit AFK Wave/Program mandate may cover the deterministic reversible
44
- metadata preparation and landing that it names. It never by itself authorizes
45
- creating or pushing the publication tag; that irreversible action requires a
46
- separate explicit confirmation.
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.
@@ -65,7 +65,7 @@ The workflow board is [Agent Workflow Kit](https://github.com/users/iKon85/proje
65
65
  "wavePrefix": "Welle"
66
66
  },
67
67
  "wrapup": {
68
- "remoteBranchSweep": false
68
+ "remoteBranchSweep": true
69
69
  }
70
70
  }
71
71
  ```
@@ -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
+ }