@event4u/agent-config 5.1.0 → 5.3.0

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/docs/guidelines/agent-infra/skill-quality-checklist.md

@@ -27,6 +27,31 @@ Every skill's YAML frontmatter MUST validate against `scripts/schemas/skill.sche
 Violations are reported by `scripts/skill_linter.py` as `schema_<rule>` errors
 and fail `python3 scripts/validate_frontmatter.py` and the full CI pipeline.
 
+### Omit fields equal to their schema default
+
+```
+NEVER write a frontmatter field whose value equals its schema `default`.
+OMIT IT — the loader injects the default at read time.
+```
+
+A field that carries the schema `default` (e.g. `trust.level: core`,
+`install.default: true`, `lifecycle: active`, `source: package`,
+`command.disable-model-invocation: true`) is redundant:
+`validate_frontmatter.apply_schema_defaults` injects it transparently for
+every consumer (validator, discovery manifest, drift checksum). Writing it
+anyway is boilerplate that `scripts/lint_frontmatter_boilerplate.py` rejects
+(wired into `task ci-fast`). To strip it across the tree, run
+`python3 scripts/migrate_frontmatter_defaults.py`. Background:
+`road-to-abstraction-reduction.md` +
+`agents/evidence/analysis/abstraction-reduction-preflight.md`.
+
+> **Changing a default is a breaking change.** The schema `default` is a
+> contract: artefacts that omit the field inherit whatever the default *is at
+> read time*. Flipping a default value (e.g. `lifecycle: active → deprecated`)
+> silently re-defaults every artefact that omits the field — so a default
+> change must pair with a re-run of `migrate_frontmatter_defaults.py` and an
+> explicit review of the affected artefacts.
+
 ## Description Triggering
 
 Claude routes skills by their frontmatter `description`. Pushy,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "5.1.0",
+    "version": "5.3.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/build_discovery_manifest.py

@@ -25,7 +25,12 @@ from typing import Any, Iterable
 import yaml
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-from validate_frontmatter import _FRONTMATTER_RE, parse_frontmatter  # noqa: E402
+from validate_frontmatter import (  # noqa: E402
+    _FRONTMATTER_RE,
+    apply_schema_defaults,
+    load_schema,
+    parse_frontmatter,
+)
 from _lib.agent_src import artefact_roots, logical_relpath, resolve_logical, strip_source_prefix  # noqa: E402
 
 ROOT = Path(__file__).resolve().parents[1]
@@ -146,11 +151,23 @@ def _trusted(path: Path) -> bool:
     return any(rel.startswith(r + "/") for r in TRUST_ROOTS)
 
 
-def _parse(path: Path) -> dict[str, Any] | None:
+# Discovery category → frontmatter schema name. `template` has no schema and
+# carries none of the defaulted fields, so it is left raw.
+_CATEGORY_SCHEMA = {"skill": "skill", "rule": "rule", "command": "command"}
+
+
+def _parse(path: Path, category: str | None = None) -> dict[str, Any] | None:
     text = path.read_text(encoding="utf-8", errors="replace")
     fm, _ = parse_frontmatter(text)
     if not isinstance(fm, dict):
         return None
+    # Inject schema defaults so an artefact that omits a field equal to its
+    # default (post abstraction-reduction migration) still presents the field
+    # to the required-key checks AND the drift checksum — keeping the checksum
+    # byte-stable across the migration (preflight Decision B).
+    schema_name = _CATEGORY_SCHEMA.get(category or "")
+    if schema_name is not None:
+        apply_schema_defaults(fm, load_schema(schema_name))
     return fm
 
 
@@ -252,7 +269,7 @@ def _build(strict: bool) -> tuple[dict[str, Any], list[dict[str, Any]]]:
         if rel in overrides:
             documented_unassigned.append({"path": rel, "category": category, "reason": overrides[rel]})
             continue
-        fm = _parse(path)
+        fm = _parse(path, category)
         payload, reason = _classify(fm, ws_ids, pack_ids)
         if reason is not None:
             unassigned.append({"path": rel, "category": category, "reason": reason})

package/scripts/check_artefact_checksums.py

@@ -32,15 +32,22 @@ DEFAULT_MANIFEST = ROOT / "dist" / "discovery" / "discovery-manifest.json"
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 # Import the same hashing primitive the builder uses so normalisation
 # stays in lockstep with the generator. (ADR-015 §Phase 6.)
-from build_discovery_manifest import _artefact_checksum  # noqa: E402
-from validate_frontmatter import parse_frontmatter  # noqa: E402
+from build_discovery_manifest import _CATEGORY_SCHEMA, _artefact_checksum  # noqa: E402
+from validate_frontmatter import apply_schema_defaults, load_schema, parse_frontmatter  # noqa: E402
 
 
-def _frontmatter(path: Path) -> dict | None:
+def _frontmatter(path: Path, category: str | None = None) -> dict | None:
     if not path.exists():
         return None
     text = path.read_text(encoding="utf-8", errors="replace")
     fm, _ = parse_frontmatter(text)
+    # Inject the same schema defaults the builder injects, so the recomputed
+    # checksum matches the committed manifest byte-for-byte even when the
+    # artefact omits a defaulted field (preflight Decision B).
+    if isinstance(fm, dict):
+        schema_name = _CATEGORY_SCHEMA.get(category or "")
+        if schema_name is not None:
+            apply_schema_defaults(fm, load_schema(schema_name))
     return fm
 
 
@@ -64,7 +71,7 @@ def _check(manifest_path: Path) -> tuple[int, list[str]]:
         if not src.exists():
             errors.append(f"{rel}: source file missing")
             continue
-        actual = _artefact_checksum(src, _frontmatter(src))
+        actual = _artefact_checksum(src, _frontmatter(src, art.get("category")))
         if actual != recorded:
             errors.append(
                 f"{rel}: checksum drift "

package/scripts/condense.py

@@ -574,7 +574,12 @@ def _parse_trust_and_owner(fm_lines):
     prefix (`finance-basic` → `finance`), then the first workspace,
     then `unknown`.
     """
-    level = None
+    # Default to the schema default `core` so the HUMAN REVIEW banner still
+    # renders if a future artefact sets `human_review_required: true` while
+    # omitting the (defaulted) `trust.level` line (abstraction-reduction
+    # preflight Decision D). The banner only fires when `hrr` is true, so this
+    # never affects artefacts that omit the whole trust block.
+    level = "core"
     hrr = False
     packs: list[str] = []
     workspaces: list[str] = []

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())