@event4u/agent-config 14.10.0 → 14.11.0

package/dist/agent-src/skills/js-library-packaging/SKILL.md

@@ -0,0 +1,173 @@
+---
+model_tier: medium
+name: js-library-packaging
+description: "Use when a JavaScript/TypeScript package is consumed by another package — exports map, peer vs. direct dependencies, files allow-list, and whether it should be built at all."
+domain: engineering
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# js-library-packaging
+
+> **Pack placement.** `engineering-base`. The step asked for it to be *suggested by* the
+> `react` and `typescript` packs, and the skill schema carries no `suggested_by` key — so the
+> intent is recorded here rather than expressed in frontmatter that would fail validation.
+> A React or TypeScript consumer receives this skill through `engineering-base`, which both
+> of those packs require.
+
+The JavaScript twin of [`composer-packages`](../composer-packages/SKILL.md). A component is
+a file; a **library** is a package with a public surface, and that surface is declared in
+`package.json` rather than inferred. Most of the failures below are silent at author time
+and loud at the consumer's — which is why the surface is read, not assumed.
+
+## The Iron Law
+
+```
+`react` AND `react-dom` ARE peerDependencies. NEVER dependencies.
+`types` IS THE FIRST KEY OF EVERY CONDITIONS OBJECT.
+DECIDE buildable-VS-source-consumed BEFORE WRITING THE EXPORTS MAP.
+NEVER HAND-BUMP A VERSION.
+```
+
+## When to use
+
+A package in the repository is imported by another package, or is about to be published:
+an `exports` map is being written or changed, a hook fails at runtime with *"invalid hook
+call"*, an install fails on a `workspace:` range, a release needs cutting, or the
+buildable-vs-source question has not been answered yet.
+
+## Procedure
+
+1. **Answer buildable-vs-source-consumed FIRST.** It determines the exports map, the `files`
+   list, and whether a build step exists at all — deciding it after writing the map means
+   rewriting the map.
+   - **Source of truth:** is the package published to a registry, or only consumed inside
+     this workspace?
+   - **Verify:** the exports targets all point into one of the two worlds (`src/` or the
+     build directory), never a mix.
+2. **Read the surface rather than asserting it.** Run the check below over the package root.
+   - **Source of truth:** `package.json` — `exports`, `dependencies`, `peerDependencies`,
+     `files`, `private`, `publishConfig`.
+   - **Verify:** zero `error`-severity findings.
+3. **Fix peer placement before anything else.** A library carrying `react` in
+   `dependencies` gives the consumer a second copy of React.
+   - **Verify:** `react` and `react-dom` appear under `peerDependencies` only.
+4. **Order the conditions.** `types` first, then `import` / `require`.
+   - **Verify:** the check reports no `types-not-first`.
+5. **Cut the release through the repository's own mechanism** — never by editing a version
+   field. See § Release.
+   - **Verify:** the version change is produced by the tool the repository already carries.
+
+## Read the surface
+
+```
+check_package_surface <library-root> [<library-root> …]
+```
+
+`scripts/check_package_surface.ts` beside this skill. Deterministic, JSON on stdout, no
+network and no subprocess. It reports:
+
+| Code | Severity | Why |
+|---|---|---|
+| `peer-as-dependency` | error | two copies of React in one tree break hooks at runtime, with a message that names neither package |
+| `export-target-missing` | error | the manifest promises a file the package does not ship |
+| `no-exports-map` | warn | `main`/`module` without `exports` — the entry point resolves by bundler convention, not by declaration |
+| `types-not-first` | warn | conditions match in declaration order, so a later `types` is never seen and the package silently ships untyped |
+| `workspace-range-publishable` | warn | a `workspace:` range does not resolve outside the workspace; published, the consumer's install fails |
+
+**It classifies from the declared export targets, never from a directory name.** A package
+directory called `ui-lib-vite` is not evidence about Vite, and one called `buildable` is not
+evidence that anything builds. A **mixed** declaration is reported as `undeclared` rather
+than resolved to a guess — declaring both is the ambiguity worth surfacing.
+
+**What it does not do:** it never compiles and never runs a bundler, so it cannot tell you
+the declared layout is producible. A checker that grew a parser would report compile errors
+as packaging errors, and the two have different fixes.
+
+## Buildable vs. source-consumed
+
+| | source-consumed | buildable |
+|---|---|---|
+| exports point at | `src/` | the build directory |
+| build step | none | one, and it must run before publish |
+| `files` | not needed (nothing published) | the build directory, as an allow-list |
+| `private` | `true` on a workspace-only package | absent; `publishConfig.access` set instead |
+| cost | consumer compiles it | a build to maintain, and output that can go stale |
+
+**Default to source-consumed inside a workspace.** A build step exists to serve publication;
+adding one for a package nobody publishes is a maintenance cost with no consumer.
+
+## Release
+
+Read the repository, then take exactly one branch — **Class A**, per
+[`standards-from-config`](../standards-from-config/SKILL.md): the config *is* the answer.
+
+1. **`.changeset/` present → changesets.** Add a changeset describing the change and let the
+   release job bump and publish. Never edit `version` by hand.
+2. **A task runner with a release command (e.g. `nx release`) → that command.** It owns
+   version, tag, and changelog together; splitting them by hand desynchronises them.
+3. **Neither present → none configured.** **Propose** a mechanism and stop. Do not hand-bump:
+   a manually edited version has no changelog entry and no tag, so the next release cannot
+   tell what shipped.
+
+A breaking change carries the `!` marker and the footer — see
+[`conventional-commits-writing`](../conventional-commits-writing/SKILL.md). The marker is
+what a release tool reads to decide the major bump, so omitting it publishes a breaking
+change as a patch.
+
+## Output format
+
+1. State the classification (source-consumed / built surface / undeclared) and where it was
+   read from.
+2. List every `error` finding with its fix, then the warnings.
+3. Name the release branch taken and the evidence in the repository for it.
+4. Say explicitly what was not checked — buildability, types, runtime behaviour.
+
+## Gotchas
+
+- **"Invalid hook call" names neither package.** The developer sees a React error and looks
+  at their component; the cause is a library shipping its own React. This is why peer
+  placement is an error and not a warning.
+- **Condition order is silent.** `{ "import": …, "types": … }` type-checks fine at author
+  time and ships untyped to the consumer.
+- **A stale build directory passes every metadata check.** The manifest points at files that
+  exist; nothing says they match `src/`. Only a real build proves that.
+- **`files` is an allow-list, not a deny-list.** Adding a directory to the package means
+  adding it here, and forgetting is invisible until a consumer imports a missing path.
+- **A `workspace:` range is not a version.** It resolves in the workspace and nowhere else.
+
+## Do NOT
+
+- Do NOT put `react` or `react-dom` in `dependencies`.
+- Do NOT write an exports map before answering buildable-vs-source-consumed.
+- Do NOT place `types` after `import` or `require`.
+- Do NOT edit a `version` field by hand, in any of the three release branches.
+- Do NOT claim the package builds because the check passed — it never ran a build.
+
+## Security constraints
+
+`scripts/check_package_surface.ts` is **read-only and offline by construction**, and the
+constraint is worth stating because a packaging tool is a tempting place to lose it:
+
+- **No network.** It never resolves a version, queries a registry, or checks whether a name
+  is taken. Every verdict comes from the manifest in front of it.
+- **No subprocess.** No package manager, no bundler, no compiler. It cannot install, build,
+  or publish, so running it on an untrusted repository executes none of that repository's code
+  — which a package manager's lifecycle scripts would.
+- **No writes.** It reads `package.json` and tests path existence. It never edits a manifest,
+  so it can never "fix" a version field, which is the one thing § Release forbids.
+- **Paths come from the caller, targets from the manifest.** Export targets are resolved
+  relative to the given root and used only for an existence test; nothing is read from them.
+
+Widening any of these turns a metadata reader into something that runs a third party's code.
+If a future check needs a build, it belongs in a separate integration test with its own
+declared cost — never here.
+
+## See also
+
+- [`composer-packages`](../composer-packages/SKILL.md) — the PHP twin; same surface discipline, different manifest.
+- [`standards-from-config`](../standards-from-config/SKILL.md) — the Class-A rule the § Release branch follows.
+- [`conventional-commits-writing`](../conventional-commits-writing/SKILL.md) — the `!` marker a release tool reads.
+- [`ui-component-architect`](../ui-component-architect/SKILL.md) — the component inside the library; this skill is the package around it.

package/dist/agent-src/skills/js-library-packaging/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+    "skill": "js-library-packaging",
+    "last_eval": "2026-08-23",
+    "description": "5 should-trigger + 5 should-not-trigger. Should-trigger covers the publish ask, the runtime symptom whose cause is packaging (invalid hook call), the exports-map question, the workspace-range install failure, and a DE phrasing. Should-not-trigger covers the near-miss neighbours this skill is one word away from: authoring the component itself (ui-component-architect), the PHP twin (composer-packages), a commit-message question (conventional-commits-writing), a monorepo task-graph question, and a bundler performance question — none of which are package-surface work.",
+    "queries": [
+        { "q": "publish our ui package", "trigger": true },
+        { "q": "why does my hook say invalid hook call", "trigger": true },
+        { "q": "what should the exports map for this library look like?", "trigger": true },
+        { "q": "the install fails on a workspace: range after publishing", "trigger": true },
+        { "q": "wie veröffentliche ich unser Komponenten-Paket richtig?", "trigger": true },
+        { "q": "build me a Button component with a loading state", "trigger": false },
+        { "q": "how do I publish a composer package?", "trigger": false },
+        { "q": "write the commit message for this breaking change", "trigger": false },
+        { "q": "why is turbo rebuilding everything on every commit?", "trigger": false },
+        { "q": "our bundle is 400kb, what should I lazy-load?", "trigger": false }
+    ]
+}

package/dist/agent-src/skills/js-library-packaging/scripts/check_package_surface.ts

@@ -0,0 +1,270 @@
+/**
+ * check_package_surface — read a JavaScript library's PACKAGE SURFACE and report what its
+ * own `package.json` says, without compiling anything.
+ *
+ * Scope, stated because the boundary is what keeps this useful: the subject is
+ * `package.json` **semantics** — the exports map, peer-dependency placement, the files
+ * allow-list, publish intent. It is NOT a build, not a type-check, and not proof that any
+ * bundler can produce the declared layout. A checker that grew a parser would start
+ * reporting compile errors as packaging errors, and the two have different fixes.
+ *
+ * The classification (`source-consumed` vs `built-surface`) is read from the DECLARED
+ * EXPORT TARGETS, never from the directory name. A fixture called `ui-lib-vite` is not
+ * evidence about Vite, and a directory called `buildable` is not evidence that anything
+ * builds — both council reviewers named that inference as the thing to avoid.
+ *
+ * Output is JSON on stdout. No network, no subprocess.
+ *
+ * Usage:
+ *   check_package_surface <library-root> [<library-root> …]
+ *   check_package_surface --self-test
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export type Severity = 'error' | 'warn';
+
+export interface Finding {
+    readonly code: string;
+    readonly severity: Severity;
+    readonly message: string;
+}
+
+export type Classification = 'source-consumed' | 'built-surface' | 'undeclared';
+
+export interface SurfaceReport {
+    readonly root: string;
+    readonly name: string | null;
+    readonly classification: Classification;
+    readonly findings: readonly Finding[];
+}
+
+/** Peer-only packages: a library that bundles these ships a second copy of them. */
+const PEER_ONLY = ['react', 'react-dom'] as const;
+
+const asRecord = (v: unknown): Record<string, unknown> =>
+    v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+
+/** Every string target reachable in an exports map, at any nesting depth. */
+export const exportTargets = (exportsField: unknown): string[] => {
+    const out: string[] = [];
+    const walk = (node: unknown): void => {
+        if (typeof node === 'string') {
+            out.push(node);
+            return;
+        }
+        if (Array.isArray(node)) {
+            for (const n of node) walk(n);
+            return;
+        }
+        for (const v of Object.values(asRecord(node))) walk(v);
+    };
+    walk(exportsField);
+    return out;
+};
+
+/**
+ * Classify from the declared targets.
+ *
+ * A package whose targets all point into a source directory is source-consumed; one whose
+ * targets point at build output is a built surface. **Mixed is `undeclared`, not a guess** —
+ * a package that declares both is making a statement this check cannot resolve, and picking
+ * one silently would hide exactly the ambiguity worth reporting.
+ */
+export const classify = (targets: readonly string[]): Classification => {
+    if (targets.length === 0) return 'undeclared';
+    const built = targets.filter((t) => /(^|\/)(dist|build|lib|out)\//.test(t));
+    if (built.length === targets.length) return 'built-surface';
+    if (built.length === 0) return 'source-consumed';
+    return 'undeclared';
+};
+
+export const checkPackage = (root: string): SurfaceReport => {
+    const manifestPath = path.join(root, 'package.json');
+    let manifest: Record<string, unknown> = {};
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as Record<string, unknown>;
+    } catch {
+        return {
+            root,
+            name: null,
+            classification: 'undeclared',
+            findings: [{ code: 'no-manifest', severity: 'error', message: `no readable package.json at ${manifestPath}` }],
+        };
+    }
+
+    const findings: Finding[] = [];
+    const deps = asRecord(manifest['dependencies']);
+    const peers = asRecord(manifest['peerDependencies']);
+    const exportsField = manifest['exports'];
+    const targets = exportTargets(exportsField);
+
+    // (a) — the "invalid hook call" failure. Two copies of React in one tree break hooks at
+    // runtime with an error that names neither package, which is why this is an error and
+    // not a warning.
+    for (const p of PEER_ONLY) {
+        if (Object.prototype.hasOwnProperty.call(deps, p)) {
+            findings.push({
+                code: 'peer-as-dependency',
+                severity: 'error',
+                message: `\`${p}\` is in dependencies; a library must declare it as a peerDependency or the consumer gets two copies (the "invalid hook call" failure)`,
+            });
+        }
+    }
+
+    // (b) — legacy entry fields with no exports map: the resolution the consumer gets then
+    // depends on their bundler rather than on this manifest.
+    const hasLegacy = ['main', 'module', 'browser'].some((k) => typeof manifest[k] === 'string');
+    if (exportsField === undefined && hasLegacy) {
+        findings.push({
+            code: 'no-exports-map',
+            severity: 'warn',
+            message: 'main/module present without an exports map — the entry point resolves by bundler convention, not by declaration',
+        });
+    }
+
+    // (c) — `types` must be the FIRST key of a conditions object. Conditional exports are
+    // matched in declaration order, so a `types` key placed after `import` is skipped by
+    // resolvers that match `import` first, and the package silently ships untyped.
+    const walkConditions = (node: unknown, at: string): void => {
+        const rec = asRecord(node);
+        const keys = Object.keys(rec);
+        if (keys.includes('types') && keys[0] !== 'types') {
+            findings.push({
+                code: 'types-not-first',
+                severity: 'warn',
+                message: `\`types\` is not the first condition at \`${at}\` (order matters: a resolver matching \`${keys[0] ?? ''}\` first never sees it)`,
+            });
+        }
+        for (const [k, v] of Object.entries(rec)) {
+            if (typeof v === 'object' && v !== null) walkConditions(v, `${at}${k}/`);
+        }
+    };
+    if (exportsField !== undefined) walkConditions(exportsField, 'exports.');
+
+    // (d) — a `workspace:` range only resolves inside the workspace. Published with no
+    // `private: true` and no publishConfig, the consumer's install fails on a protocol
+    // their registry has never heard of.
+    const allDeps = { ...deps, ...asRecord(manifest['devDependencies']), ...peers };
+    const workspaceRanges = Object.entries(allDeps).filter(([, v]) => typeof v === 'string' && v.startsWith('workspace:'));
+    if (
+        workspaceRanges.length > 0 &&
+        manifest['private'] !== true &&
+        manifest['publishConfig'] === undefined
+    ) {
+        findings.push({
+            code: 'workspace-range-publishable',
+            severity: 'warn',
+            message: `${String(workspaceRanges.length)} \`workspace:\` range(s) in a package that is neither private nor carrying publishConfig — the protocol does not resolve outside the workspace`,
+        });
+    }
+
+    // A declared target that is not in the tree is the drift the whole surface rests on.
+    for (const t of targets) {
+        if (!t.startsWith('.')) continue;
+        if (!fs.existsSync(path.join(root, t))) {
+            findings.push({
+                code: 'export-target-missing',
+                severity: 'error',
+                message: `exports target \`${t}\` does not exist in the package`,
+            });
+        }
+    }
+
+    const name = typeof manifest['name'] === 'string' ? manifest['name'] : null;
+    return { root, name, classification: classify(targets), findings };
+};
+
+/** Registry item types deprecated in v4 — writing one produces an item the CLI cannot read. */
+const DEPRECATED_ITEM_TYPES = ['registry:build', 'registry:mcp'] as const;
+
+/**
+ * Check a `registry.json` (or a single `registry-item.json`) published by a library.
+ *
+ * Same subject as the manifest checks: what the file DECLARES. A registry item that lists
+ * `react` in `dependencies` reproduces the two-copies-of-React failure one layer up — the
+ * consumer's app already has React, and the item installs a second.
+ */
+export const checkRegistry = (file: string): Finding[] => {
+    let doc: Record<string, unknown> = {};
+    try {
+        doc = JSON.parse(fs.readFileSync(file, 'utf8')) as Record<string, unknown>;
+    } catch {
+        return [{ code: 'no-registry', severity: 'error', message: `no readable registry JSON at ${file}` }];
+    }
+    // Both shapes are legal: an index with `items`, or a single item.
+    const items = Array.isArray(doc['items']) ? (doc['items'] as unknown[]) : [doc];
+    const findings: Finding[] = [];
+    for (const raw of items) {
+        const item = asRecord(raw);
+        const name = typeof item['name'] === 'string' ? item['name'] : '(unnamed)';
+        const deps = Array.isArray(item['dependencies']) ? (item['dependencies'] as unknown[]) : [];
+        for (const d of deps) {
+            const dep = String(d).split('@')[0];
+            if (PEER_ONLY.includes(dep as (typeof PEER_ONLY)[number])) {
+                findings.push({
+                    code: 'registry-item-bundles-peer',
+                    severity: 'error',
+                    message: `registry item \`${name}\` lists \`${dep}\` in dependencies; the consuming app already has it, and installing a second copy is the same "invalid hook call" failure one layer up`,
+                });
+            }
+        }
+        const type = typeof item['type'] === 'string' ? item['type'] : '';
+        if (DEPRECATED_ITEM_TYPES.includes(type as (typeof DEPRECATED_ITEM_TYPES)[number])) {
+            findings.push({
+                code: 'registry-item-deprecated-type',
+                severity: 'error',
+                message: `registry item \`${name}\` uses \`${type}\`, deprecated in v4 — use \`registry:base\` or \`registry:font\``,
+            });
+        }
+    }
+    return findings;
+};
+
+const selfTest = (): number => {
+    let failed = 0;
+    const check = (label: string, cond: boolean): void => {
+        if (!cond) {
+            process.stderr.write(`❌  ${label}\n`);
+            failed += 1;
+        }
+    };
+
+    check('a source target classifies as source-consumed', classify(['./src/index.ts']) === 'source-consumed');
+    check('a dist target classifies as built-surface', classify(['./dist/index.js']) === 'built-surface');
+    check('a MIXED declaration is undeclared, never guessed', classify(['./src/index.ts', './dist/index.js']) === 'undeclared');
+    check('no targets is undeclared', classify([]) === 'undeclared');
+    check(
+        'nested conditions are all collected',
+        exportTargets({ '.': { types: './a.d.ts', import: './b.js' } }).length === 2,
+    );
+
+    process.stdout.write(
+        failed === 0 ? '✅  check_package_surface: self-test passed\n' : `❌  ${String(failed)} failure(s)\n`,
+    );
+    return failed === 0 ? 0 : 1;
+};
+
+const main = (): number => {
+    const argv = process.argv.slice(2);
+    if (argv.includes('--self-test')) return selfTest();
+    const roots = argv.filter((a) => !a.startsWith('--'));
+    if (roots.length === 0) {
+        process.stderr.write('usage: check_package_surface <library-root> [...]\n');
+        return 2;
+    }
+    // A path ending in a registry file is checked as a registry, not as a package root —
+    // otherwise the caller has to know which of two checkers to reach for.
+    const reports = roots.map((r) =>
+        /registry(-item)?\.json$/.test(r)
+            ? { root: r, name: null, classification: 'undeclared' as Classification, findings: checkRegistry(r) }
+            : checkPackage(r),
+    );
+    process.stdout.write(`${JSON.stringify({ reports }, null, 2)}\n`);
+    return reports.some((r) => r.findings.some((f) => f.severity === 'error')) ? 1 : 0;
+};
+
+if (process.argv[1] !== undefined && process.argv[1].includes('check_package_surface')) {
+    process.exit(main());
+}

package/dist/agent-src/skills/laravel-migration/SKILL.md

@@ -13,6 +13,9 @@ trust:
 install:
   default: false
   removable: true
+triggers:
+  - phrase: "make:migration"
+  - phrase: "laravel migration"
 ---
 
 # laravel-migration

package/dist/agent-src/skills/learning-to-rule-or-skill/SKILL.md

@@ -4,6 +4,9 @@ name: learning-to-rule-or-skill
 description: "Use when a repeated learning, mistake, or successful pattern should be turned into a new rule or skill. Also use after completing a task to capture learnings from the work."
 source: project
 domain: process
+scope:
+  write: []
+  verification_reason: "execution.handler is internal, so this skill spawns no subprocess — writes happen through the agent's declared allowed_tools. No command can prove a scope the skill never executes."
 execution:
   type: assisted
   handler: internal

package/dist/agent-src/skills/lint-skills/SKILL.md

@@ -3,6 +3,9 @@ model_tier: medium
 name: lint-skills
 description: "Use when running the package's skill linter against all skills and rules to validate frontmatter, required sections, and execution metadata."
 domain: process
+scope:
+  write: []
+  verification_reason: "the declared command is a read-only linter: grep -c 'writeFileSync|mkdirSync|appendFileSync' src/scripts/skill_linter.ts returns 0. Absence of a write is not something a command can prove."
 execution:
   type: assisted
   handler: shell

package/dist/agent-src/skills/llm-provider-knowledge/SKILL.md

@@ -18,6 +18,9 @@ trust:
   level: experimental
 install:
   removable: true
+scope:
+  write: []
+  verification_reason: "execution declares no handler, so this skill runs nothing of its own — every write is the calling agent's, under the rules that govern it. No command can prove a scope the skill never executes."
 execution:
   type: manual
 ---