@event4u/agent-config 5.1.0 → 5.2.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "5.1.0",
+    "version": "5.2.0",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -802,6 +802,22 @@ our recommendation order, not its support status.
 > that forces a new era split (`# Era: 4.6.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [5.2.0](https://github.com/event4u-app/agent-config/compare/5.1.0...5.2.0) (2026-05-29)
+
+### Features
+
+* **ci:** reject sloppy commit subjects before they leak into the changelog ([26a94e9](https://github.com/event4u-app/agent-config/commit/26a94e9e0f07e862a135cfc96b742a999e7131ec))
+
+### Documentation
+
+* **adr:** land ADR-033 distribution-identity npm-primary ([63d38cf](https://github.com/event4u-app/agent-config/commit/63d38cf75df6506218cfc6bc17f0b5ba0c90fe9d))
+
+### Chores
+
+* **roadmaps:** flip distribution-identity Phase 1-3 + regen dashboard ([0885b9d](https://github.com/event4u-app/agent-config/commit/0885b9d4dda67a2439fc5292367249fa99766a02))
+
+Tests: 5186 (+26 since 5.1.0)
+
 ## [5.1.0](https://github.com/event4u-app/agent-config/compare/5.0.0...5.1.0) (2026-05-29)
 
 ### Features

package/README.md

@@ -37,10 +37,15 @@ Beyond software: [`user-types/`](packages/core/.agent-src.uncondensed/user-types
 
 <p align="center">
   <a href="CHANGELOG.md">CHANGELOG</a> ·
+  <a href="CHANGELOG.md#breaking--v400-unified-setup-road-to-unified-setup">Breaking changes</a> ·
   <a href="https://github.com/event4u-app/agent-config/releases/latest">Latest release</a> ·
   <a href="https://github.com/event4u-app/agent-config/discussions">Discussions</a>
 </p>
 
+<p align="center">
+  <sub>Distribution: <code>npm install @event4u/agent-config</code> · npm-primary per <a href="docs/decisions/ADR-033-distribution-identity-npm-primary.md">ADR-033</a>. Major bumps follow <a href="CONTRIBUTING.md#versioning-policy">semver</a>; each ships a <a href="CHANGELOG.md#breaking--v400-unified-setup-road-to-unified-setup"><code>### Breaking</code></a> entry.</sub>
+</p>
+
 ---
 
 ## Use it in your project

package/dist/discovery/deprecation-report.md

@@ -1,6 +1,6 @@
 # Discovery — Deprecation Report
 
-- Generated: `2026-05-29T12:00:12Z`
+- Generated: `2026-05-29T14:14:52Z`
 - Deprecated artefacts: **0**
 
 _None. Tree is clean._

package/dist/discovery/discovery-manifest.json

@@ -9565,7 +9565,7 @@
       "reason": "scaffold for new SKILL.md authoring"
     }
   ],
-  "generated_at": "2026-05-29T12:00:12Z",
+  "generated_at": "2026-05-29T14:14:52Z",
   "packs": [
     {
       "artefact_count": 85,

package/dist/discovery/discovery-manifest.json.sha256

@@ -1 +1 @@
-6e36d1bdab54a687328a853b8cbeee77060ad359c006180c0109daa959eba603  discovery-manifest.json
+c0a417183acd5273d0cd21648816539b30da57dd1840f7e967f67ef90a1cffe5  discovery-manifest.json

package/dist/discovery/discovery-manifest.summary.md

@@ -1,6 +1,6 @@
 # Discovery Manifest — Summary
 
-- Generated: `2026-05-29T12:00:12Z`
+- Generated: `2026-05-29T14:14:52Z`
 - Scanner: `d75eba636abb`
 - Artefacts: **433**
 - Unassigned: **0**

package/dist/discovery/orphan-report.md

@@ -1,6 +1,6 @@
 # Discovery — Orphan Report
 
-- Generated: `2026-05-29T12:00:12Z`
+- Generated: `2026-05-29T14:14:52Z`
 - Orphan artefacts: **0**
 
 > An orphan is an artefact whose declared pack has no other members.

package/dist/discovery/packs.json

@@ -1,6 +1,6 @@
 {
   "checksum": "sha256:653636e679543062954910f794e458eb8424d7f2618b889a29969d21c74fcf0e",
-  "generated_at": "2026-05-29T12:00:12Z",
+  "generated_at": "2026-05-29T14:14:52Z",
   "packs": [
     {
       "artefact_count": 85,

package/dist/discovery/trust-report.md

@@ -1,6 +1,6 @@
 # Discovery — Trust Report
 
-- Generated: `2026-05-29T12:00:12Z`
+- Generated: `2026-05-29T14:14:52Z`
 - Workspaces tracked: **8**
 - Human-review-required artefacts: **2**
 

package/dist/discovery/workspaces.json

@@ -1,6 +1,6 @@
 {
   "checksum": "sha256:653636e679543062954910f794e458eb8424d7f2618b889a29969d21c74fcf0e",
-  "generated_at": "2026-05-29T12:00:12Z",
+  "generated_at": "2026-05-29T14:14:52Z",
   "scanner_version": "d75eba636abb",
   "workspaces": [
     {

package/dist/mcp/registry-manifest.json

@@ -9,7 +9,7 @@
     "homepage": "https://github.com/event4u-app/agent-config#readme",
     "name": "@event4u/agent-config",
     "repository": "https://github.com/event4u-app/agent-config",
-    "version": "5.1.0"
+    "version": "5.2.0"
   },
   "registries": [
     {

package/docs/decisions/ADR-033-distribution-identity-npm-primary.md

@@ -0,0 +1,81 @@
+---
+adr: 033
+status: accepted
+date: 2026-05-29
+decision: distribution-identity-npm-primary
+supersedes: —
+superseded_by: —
+phase: distribution-identity
+type: structural
+review_date: 2026-08-29
+---
+
+# ADR-033 — Distribution identity: npm-primary, Packagist deprecated-in-place
+
+## Status
+
+**Accepted** · 2026-05-29. AI Council (claude-sonnet-4-5 + gpt-4o, analysis lens, 2026-05-29) converged on **npm-primary with Packagist deprecated-in-place**. No maintainer veto surfaced; the de-facto evidence and the operational-honesty argument both point to a single answer. Review date 2026-08-29.
+
+## Context
+
+External feedback rounds 10 / 12 / 13 returned to two recurring symptoms — *"Packagist still shows 1.0.4"* and *"two major bumps in six days with no breaking-change signal"*. A council deliberation (lens: analysis) re-framed both as **one distribution-identity question** the repo has answered in practice but never recorded:
+
+- **`package.json` at `5.1.0`** — the package is past the unified-setup 4.0.0 major and a subsequent 5.0.0 line; semver discipline (per `CONTRIBUTING.md § Versioning policy`) treats installer-layout changes as major, so the cadence is policy-correct.
+- **`scripts/release.py` invokes `npm publish` exclusively** — the only publish surface that ships from a release run.
+- **No `composer.json` exists in this repo** — the file was removed during the npm pivot (pre-3.x era). The Packagist `event4u/agent-config` 1.0.4 listing is a zombie pointing at a repository state that no longer exists.
+- **No automation syncs the Composer surface** — none has existed since the pivot. Pretending the channel is supported is a maintenance lie.
+- **ADR-027** already locks the changelog-machine path (`scripts/release.py` derives `CHANGELOG.md § Breaking` from Conventional Commits). The "no breaking-change signal" symptom is stale against that surface — what is missing is a one-click pointer for consumers.
+
+Council framing — two perspectives surfaced:
+
+**Lens A — Strategic / consumer-positioning.** A consumer who lands on Packagist sees 1.0.4 and installs an artefact the repo cannot support. The honest signal is deprecation; dual-track without resources is worse than a single declared channel.
+
+**Lens B — Technical / operational-honesty.** A channel is "supported" only if a release pipeline publishes to it. Composer/Packagist has had no such pipeline since the npm pivot. The simpler invariant — *one channel, one truth* — wins on every measurable axis: maintenance load, consumer trust, audit clarity.
+
+Both lenses converged.
+
+## Decision
+
+1. **The package is npm-primary.** The canonical install path is `npm install @event4u/agent-config` (and the consumer-facing `npx @event4u/agent-config install` wizard). All release tooling (`scripts/release.py`, `package.json`, `CONTRIBUTING.md § Versioning policy`) already aligns with this surface — this ADR records the policy, no code changes follow from the declaration itself.
+
+2. **Composer / Packagist is deprecated-in-place.** No `composer.json` ships from this repo; no PHP autoload surface is supported; the Packagist `event4u/agent-config` 1.0.4 listing is treated as legacy and gets a deprecation pointer through the only mechanism available to a deleted-composer-json repo: a registry-side claim/archive action by the maintainer. The corresponding human-owner item is surfaced in `docs/distribution/registries.md` (see Phase 2 of the [`road-to-distribution-identity.md`](../../agents/roadmaps/road-to-distribution-identity.md) roadmap).
+
+3. **Breaking-change communication uses `CHANGELOG.md § Breaking`.** ADR-027 locked the auto-generated changelog from Conventional Commits. This ADR adds one consumer-facing affordance — a README / distribution-doc pointer linking that section — so a consumer who sees a major-version bump has a one-click path to *what broke, what to do*. No new `BREAKING_CHANGES.md` file unless the maintainer prefers one.
+
+4. **Commit-subject hygiene is enforced in CI.** Because the changelog generator reads commit subjects verbatim, sloppy subjects (`leftover`, `wip`, `temp`, `fixup`, or sub-10-character one-word entries) leak directly into the public changelog. A CI lint (`task lint-commit-subjects` or sibling) rejects those subjects on PR. This is wired in Phase 3 of the same roadmap and is the one hygiene item that ties directly to distribution identity.
+
+## Consequences
+
+**Positive:**
+
+- The distribution story is **single-channel, single-truth**. Anyone scanning the package — consumer, contributor, auditor, package-registry crawler — gets one consistent answer.
+- The zombie Packagist listing no longer misdirects PHP-shop consumers (once the maintainer files the registry-side archive action).
+- Breaking-change discoverability is two clicks from the README: "release notes" → `CHANGELOG.md § Breaking`. No bespoke `BREAKING_CHANGES.md` to maintain.
+- CI catches sloppy commit subjects before they become public changelog lines — the changelog is as clean as the gate that feeds it.
+
+**Negative / accepted costs:**
+
+- A PHP-shop consumer who depends on the 1.0.4 Packagist release is left behind. Mitigation: clear deprecation notice + npm install pointer in the registry-side archive.
+- The maintainer must perform a one-time login at `packagist.org/packages/event4u/agent-config` to claim or archive the listing — autonomous tooling cannot do that.
+- Future re-entry into the Composer ecosystem would require a new ADR superseding this one. That cost is acceptable: a re-entry would be a strategic redirect, not a quiet re-add.
+
+**Operationally neutral:**
+
+- `scripts/release.py` already does the right thing; no script change follows from this ADR.
+- `CONTRIBUTING.md § Versioning policy` already does the right thing; no policy change follows from this ADR. The major bumps that prompted the feedback (4.0.0 unified-setup, 5.0.0 follow-up) were policy-correct under the existing rule.
+
+## Alternatives considered
+
+- **Dual-track with auto-sync.** Rejected. The repo carries no Composer surface to sync; restoring one would mean re-introducing a `composer.json` + a sync pipeline + a PHP-side autoload story, all to support a consumer base nobody has named. The carrying cost outweighs the demand signal.
+- **Dual-track without auto-sync (status quo).** Rejected. This is the failure mode that produced the external feedback in the first place — a stale 1.0.4 listing pretends a channel is supported when it is not. Operational-honesty argument carries.
+- **Re-introduce composer.json as a stub linking to npm.** Rejected. A stub on Packagist is still a Packagist artifact; consumers may still try to `composer require` it and hit a non-functional package. Registry-side archive is the cleaner signal.
+- **A bespoke `BREAKING_CHANGES.md` file.** Rejected by default; ADR-027 already locks the machine-generated changelog as the breaking-change surface. Maintainer may revisit if the changelog format proves insufficient for end-of-life or migration-guide-shape communication.
+
+## References
+
+- [`agents/roadmaps/road-to-distribution-identity.md`](../../agents/roadmaps/road-to-distribution-identity.md) — the work-item plan this ADR underwrites.
+- [`ADR-027-changelog-machine-vs-manual.md`](ADR-027-changelog-machine-vs-manual.md) — the prior decision locking the auto-generated changelog.
+- [`CONTRIBUTING.md § Versioning policy`](../../CONTRIBUTING.md) — the semver discipline this ADR confirms.
+- [`docs/distribution/registries.md`](../distribution/registries.md) — external-registry submission posture; this ADR adds a distribution-channel-identity section to that file.
+- `scripts/release.py` — the `npm publish` release pipeline.
+- External feedback rounds 10 / 12 / 13 (private session transcripts; convergence summary inlined above to keep this ADR self-contained).

package/docs/decisions/INDEX.md

@@ -36,6 +36,7 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-030](ADR-030-claude-code-command-projection.md) | Claude Code Command Projection | accepted | 2026-05-28 | — |
 | [ADR-031](ADR-031-validation-severity-tiers-and-projection-roundtrip.md) | Validation Severity Tiers And Projection Roundtrip | accepted | 2026-05-29 | — |
 | [ADR-032](ADR-032-linked-projects-scope.md) | Linked Projects Scope Go Option A | accepted | 2026-05-29 | — |
+| [ADR-033](ADR-033-distribution-identity-npm-primary.md) | Distribution Identity Npm Primary | accepted | 2026-05-29 | — |
 
 ## Unnumbered (legacy)
 

package/docs/distribution/registries.md

@@ -4,6 +4,35 @@ Track third-party registries / directories we want this package to surface in. S
 
 > **Authority** — Phase 2 of [`road-to-product-adoption.md`](../../agents/roadmaps/road-to-product-adoption.md). The autonomous roadmap pass cannot open PRs in third-party repos; this file is the handoff.
 
+## Distribution channels — npm-primary
+
+Per [`ADR-033`](../decisions/ADR-033-distribution-identity-npm-primary.md), the package is **npm-primary, Packagist deprecated-in-place**. Both lenses of the council deliberation (strategic / operational) converged on a single-channel posture: this is the canonical record of which registries we publish to vs. which we treat as legacy.
+
+| Channel | Status | Canonical install | Notes |
+|---|---|---|---|
+| npm — `@event4u/agent-config` | **Primary** | `npm install @event4u/agent-config` or `npx @event4u/agent-config install` | The release pipeline (`scripts/release.py`) runs `npm publish` exclusively; `package.json` is the source of truth for the published version. |
+| Packagist — `event4u/agent-config` | **Deprecated-in-place** | (do not install — see ADR-033) | The 1.0.4 listing is a legacy artefact from the pre-3.x repo namespace. No `composer.json` ships from this repo. Maintainer-side claim/archive action required (see below). |
+
+### Packagist deprecation — human-owner item
+
+The Packagist `event4u/agent-config` listing pins at 1.0.4 from a repository state that no longer exists. The autonomous pipeline cannot retire that listing — it requires a maintainer login at `packagist.org/packages/event4u/agent-config`. Two paths exist; either is acceptable per ADR-033.
+
+- [ ] **Claim + abandoned-flag the package.** Log in at packagist.org, claim the `event4u/agent-config` namespace, set the package to `abandoned` with the replacement pointer `event4u/agent-config` on npm (or the npm package URL as a body note where Packagist's abandoned-replacement field expects a Composer-namespace value, fall back to a `description` field redirect).
+- [ ] **OR: leave the listing as legacy + add a description-field redirect.** If claim is blocked or out of scope, edit the listing description to add a one-line `> Deprecated — install via npm: \`@event4u/agent-config\`` so any consumer who lands there sees the correct path.
+
+This item is **owner-owned**, not autonomous; the roadmap explicitly captures it as such (`road-to-distribution-identity.md` Phase 2 Step 1). Mark the chosen path with `[x]` once executed.
+
+### Breaking-change communication
+
+Major-version bumps are policy-correct per [`CONTRIBUTING.md § Versioning policy`](../../CONTRIBUTING.md) (semver — installer-layout changes are major). The auto-generated `CHANGELOG.md § Breaking` section is the **single source of truth** for breaking changes; [`ADR-027`](../decisions/ADR-027-changelog-machine-vs-manual.md) locks the machine-generated path.
+
+Consumers who see a major-version bump should follow:
+
+1. [`CHANGELOG.md § Breaking`](../../CHANGELOG.md#breaking) — the diff between the prior and the new major. Every breaking change carries a Conventional-Commits subject prefixed `feat!:` or with a `BREAKING CHANGE:` footer.
+2. The release-line link in the GitHub release entry for the new version (links the auto-generated changelog section).
+
+No bespoke `BREAKING_CHANGES.md` is maintained — the changelog is the authoritative surface.
+
 ## Submission status
 
 | # | Registry | URL | Submission shape | Status | PR link |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "5.1.0",
+    "version": "5.2.0",
     "description": "Universal AI Agent OS \u2014 audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/scripts/lint_commit_subjects.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Reject commit subjects that would leak into the auto-generated changelog.
+
+`scripts/release.py` reads commit subjects verbatim from
+`<prev-tag>..HEAD` and writes them into `CHANGELOG.md` sections (notably
+`### Breaking`). A sloppy subject — `wip`, `commit leftovers`, `fixup`,
+short typos — becomes a sloppy public changelog line. Per
+[ADR-033](../docs/decisions/ADR-033-distribution-identity-npm-primary.md)
+and Phase 3 of `road-to-distribution-identity.md` this lint is the
+CI-enforced gate that closes that surface.
+
+Rules (PRO commit, range `<base>..<head>`):
+
+- Subject length **after** stripping the Conventional-Commits type-prefix
+  (`feat:` / `fix(scope):` / `chore!:` / …) must be ≥ 10 characters.
+- Subject must not contain blocklist words as whole tokens:
+  `leftover` / `leftovers` / `wip` / `temp` / `tmp` / `fixup`.
+  Case-insensitive; matched on word boundaries so legitimate uses like
+  `template` or `tempor­ary` (rare) survive — the linter targets the
+  short hand-wave forms reviewers see in feedback rounds.
+
+Carve-outs:
+
+- Merge commits (`Merge pull request …`, `Merge branch …`) are skipped —
+  they are GitHub-generated and not consumer-visible in the changelog.
+- Revert commits (`Revert "…"`) are skipped — they ride the original
+  subject's discipline.
+
+Local invocation defaults to `origin/main..HEAD` (the "what I am about
+to push" range). CI sets `--base $GITHUB_BASE_REF --head $GITHUB_SHA`.
+
+Cap: ≤ 150 LOC, stdlib only. Hooked into `task ci` via
+`task lint-commit-subjects`.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+
+BLOCKLIST = frozenset({"leftover", "leftovers", "wip", "temp", "tmp", "fixup"})
+MIN_SUBJECT_LEN = 10
+
+# Conventional Commits prefix — `type(scope)!?: message`. Matches the
+# heads our `scripts/release.py` and CHANGELOG section logic respect.
+CONVENTIONAL_PREFIX = re.compile(
+    r"^(feat|fix|chore|docs|refactor|test|perf|style|build|ci|revert)"
+    r"(\([^)]+\))?!?:\s+",
+    re.IGNORECASE,
+)
+
+# Skip lines — GitHub-generated merge subjects and revert commits.
+SKIP_PREFIXES = ("Merge pull request", "Merge branch", "Merge remote-tracking",
+                 'Revert "')
+
+
+def fetch_subjects(base: str, head: str) -> list[str]:
+    """Return one commit subject per element. Empty on no-range / no-commits."""
+    try:
+        result = subprocess.run(
+            ["git", "log", f"{base}..{head}", "--format=%s", "--no-merges"],
+            capture_output=True, text=True, check=True,
+        )
+    except subprocess.CalledProcessError as exc:
+        # CI without a proper base ref (force-push, first commit, weird state).
+        # Lint is advisory in that case — never block on git plumbing failures.
+        print(f"⚠️  git log {base}..{head} failed: {exc.stderr.strip()}",
+              file=sys.stderr)
+        return []
+    return [line.strip() for line in result.stdout.splitlines() if line.strip()]
+
+
+def check_subject(subject: str) -> list[str]:
+    """Return list of issue strings for the subject; empty = clean."""
+    if any(subject.startswith(p) for p in SKIP_PREFIXES):
+        return []
+    issues: list[str] = []
+    body = CONVENTIONAL_PREFIX.sub("", subject, count=1)
+    if len(body) < MIN_SUBJECT_LEN:
+        issues.append(
+            f"subject body < {MIN_SUBJECT_LEN} chars after Conventional-Commits "
+            f"prefix: {subject!r}"
+        )
+    tokens = {t.lower() for t in re.findall(r"[A-Za-z]+", body)}
+    hits = sorted(tokens & BLOCKLIST)
+    if hits:
+        issues.append(
+            f"blocklist token(s) {hits} in subject: {subject!r}"
+        )
+    return issues
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--base", default="origin/main",
+                        help="base ref (default: origin/main)")
+    parser.add_argument("--head", default="HEAD",
+                        help="head ref (default: HEAD)")
+    parser.add_argument("--quiet", action="store_true",
+                        help="suppress the clean-pass success line")
+    args = parser.parse_args()
+
+    subjects = fetch_subjects(args.base, args.head)
+    if not subjects:
+        if not args.quiet:
+            print(f"✅  No commit subjects to check in "
+                  f"{args.base}..{args.head}.")
+        return 0
+
+    failures: list[tuple[str, str]] = []
+    for subj in subjects:
+        for issue in check_subject(subj):
+            failures.append((subj, issue))
+
+    if failures:
+        print(f"❌  {len(failures)} commit-subject issue(s) in "
+              f"{args.base}..{args.head}:", file=sys.stderr)
+        for _, issue in failures:
+            print(f"   - {issue}", file=sys.stderr)
+        print(
+            "\nThese subjects feed the auto-generated CHANGELOG.md via "
+            "scripts/release.py — sloppy subjects become sloppy public "
+            "changelog lines. Per ADR-033 + "
+            "agents/roadmaps/road-to-distribution-identity.md § Phase 3.\n"
+            "Fix: rewrite the offending commits (e.g. `git rebase -i "
+            f"{args.base}` and `r`eword) with descriptive subjects, "
+            "then re-push.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if not args.quiet:
+        print(f"✅  {len(subjects)} commit subject(s) clean.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())