@event4u/agent-config 9.36.0 → 10.1.0

package/src/scripts/schemas/skill.schema.json

@@ -33,6 +33,48 @@
       "maxLength": 500,
       "description": "Agent-Skills spec field (optional): machine-readable declaration of environment requirements — system packages, network access, product/host constraints. Mirrors the public spec so media/doc skills can state requirements outside prose."
     },
+    "runtime_requires": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Structured runtime prerequisites, in the form `doctor`/`preflight` can actually probe. The free-text `compatibility` field above states requirements for a human reader; this states them for a machine, and the two coexist deliberately — `compatibility` mirrors the public Agent-Skills spec and is not replaced here. Mandatory for an external `execution.handler` (shell/node/php), which cannot run without declared dependencies; meaningless for `internal`, which by definition needs no external binary. NOT named `requires`: that key is taken by ADR-015 pack-dependency edges (a list of pack ids, validated in build_discovery_manifest.ts), and reusing it makes every skill carrying one unassignable in the discovery manifest.",
+      "properties": {
+        "bins": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Executables that must resolve on PATH (e.g. `python3`, `curl`). Probed by name, never by version — a version constraint belongs in the skill body where it can explain itself."
+        },
+        "env": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Z][A-Z0-9_]*$"
+          },
+          "description": "Environment variable NAMES that must be set. Names only — a value here would be a credential in a tracked file (secret-vcs-guard)."
+        },
+        "primary_env": {
+          "type": "string",
+          "pattern": "^[A-Z][A-Z0-9_]*$",
+          "description": "The one variable from `env` whose absence makes the skill unusable rather than degraded, so a doctor report can distinguish a hard block from a partial one. Must also appear in `env`. HALF-ENFORCED, stated plainly: the `dependencies` keyword below requires `env` to be present whenever `primary_env` is, which is the part JSON Schema can express. That the named variable is a MEMBER of `env` is NOT checked anywhere — the linter reads frontmatter by regex, and a fragile pattern on a blocking rule is worse than an honest gap. Zero skills use the field today; the membership check belongs in the doctor wiring (Phase 1, gated on S0.3), where the value is parsed rather than matched."
+        },
+        "network": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Egress hostnames the skill contacts, checked against the egress allowlist. An empty array is a positive claim of no network access and is NOT the same as omitting the key."
+        }
+      },
+      "dependencies": {
+        "primary_env": [
+          "env"
+        ]
+      },
+      "$comment": "road-to-skill-ecosystem-executable-payloads Phase 1 (defect D2): `compatibility` is free text used by 2 skills, so cmd_doctor.ts / cmd_preflight.ts had nothing structured to verify. Named `runtime_requires` because `requires` is reserved for ADR-015 pack edges. The `dependencies` keyword closes the half of the primary_env invariant a schema can express; R2 review finding 1 flagged the fully-unenforced version as the same ADR-127 shape this roadmap is closing."
+    },
     "provenance": {
       "type": "string",
       "enum": [

package/src/scripts/skill_linter.ts

@@ -230,6 +230,30 @@ const KERNEL_RULE_IDS = new Set([
 export const VALID_EXECUTION_TYPES = new Set(['manual', 'assisted', 'automated']);
 export const VALID_EXECUTION_HANDLERS = new Set(['none', 'shell', 'php', 'node', 'internal']);
 const VALID_EXECUTION_SAFETY_MODES = new Set(['strict']);
+/**
+ * Handlers that shell out of this process and therefore depend on something the
+ * host must already have. `internal` is deliberately absent: it runs in-process
+ * and by definition needs no external binary, so demanding a `requires` block
+ * from it would produce a pro-forma declaration rather than a checkable fact.
+ */
+const EXTERNAL_EXECUTION_HANDLERS = new Set(['shell', 'php', 'node']);
+/**
+ * Top-level `runtime_requires:` declaration (sibling of `execution:`, not a field
+ * inside it). Deliberately NOT `requires:` — that key is ADR-015 pack-dependency
+ * edges (a list of pack ids), and a skill carrying an object there is rejected by
+ * `build_discovery_manifest.ts` as unassignable.
+ *
+ * Matches block style (`runtime_requires:` then indented keys) AND flow style
+ * (`runtime_requires: {bins: [...]}`). The block-only version was an R2 review
+ * finding: flow style is valid YAML and valid against the schema, so erroring on
+ * it told the author to add a declaration they already had, with no suppression
+ * path. The neighbouring `^execution:\s*$` is block-only by house convention, but
+ * its consequence is a silent skip rather than a hard error.
+ *
+ * `[ \t]*` rather than `\s*`: `\s` matches a newline, so the looser form could
+ * span lines and accept a bare key whose value sits somewhere below it.
+ */
+const RUNTIME_REQUIRES_BLOCK_PATTERN = /^runtime_requires:[ \t]*(\{.*)?$/m;
 const VALID_EXECUTION_FIELDS = new Set([
     'type',
     'handler',
@@ -1264,7 +1288,14 @@ function lint_wing4_boundaries(text: string): Issue[] {
     return issues;
 }
 
-function lint_execution_metadata(execution: ExecutionBlock): Issue[] {
+/**
+ * `frontmatter` is required, not defaulted. An R2 review finding: with
+ * `frontmatter = ''` an omitted argument makes the runtime-requires check
+ * FABRICATE its error rather than skip it, which is the wrong failure direction
+ * for an optional parameter — a future caller that forgets it gets a confident
+ * error about a declaration it never looked for.
+ */
+function lint_execution_metadata(execution: ExecutionBlock, frontmatter: string): Issue[] {
     const issues: Issue[] = [];
 
     const execType = execution.type;
@@ -1374,6 +1405,30 @@ function lint_execution_metadata(execution: ExecutionBlock): Issue[] {
         }
     }
 
+    // An external handler that actually declares a command depends on binaries or
+    // env the host may not have; without a `runtime_requires` block,
+    // `doctor`/`preflight` have nothing to probe and the failure surfaces mid-run
+    // instead. Gated on a declared `command:` on purpose — a `handler: shell` skill
+    // with no command is advisory prose, and demanding requirements from it would be
+    // a pro-forma field.
+    if (
+        typeof handler === 'string' &&
+        EXTERNAL_EXECUTION_HANDLERS.has(handler) &&
+        Array.isArray(command) &&
+        command.length > 0 &&
+        !RUNTIME_REQUIRES_BLOCK_PATTERN.test(frontmatter)
+    ) {
+        issues.push(
+            new Issue(
+                'error',
+                'missing_runtime_requires',
+                `execution.handler '${handler}' declares a command but the skill has no top-level ` +
+                    "'runtime_requires:' block — declare bins/env/network so doctor and preflight can " +
+                    'verify the runtime before the command runs',
+            ),
+        );
+    }
+
     const unknown = Object.keys(execution).filter((k) => !VALID_EXECUTION_FIELDS.has(k));
     for (const field of unknown.sort()) {
         issues.push(
@@ -1530,7 +1585,7 @@ export function lint_skill(p: string, text: string, absPath: string | null = nul
 
         const execution = parseExecutionBlock(frontmatter);
         if (execution !== null) {
-            issues.push(...lint_execution_metadata(execution));
+            issues.push(...lint_execution_metadata(execution, frontmatter));
         }
 
         const tierMatch = TIER_PATTERN.exec(frontmatter);

package/src/server/schemas/settings.ts

@@ -529,20 +529,12 @@ export const settingsSchema = z.object({
                 'PreToolUse code-graph nudge (ADR-124 Phase 4). Default off. When on AND a native code-graph cache or a consumer-shipped graph.json/SCIP index is present, warns once per session (never blocks) as the agent is about to Grep/Glob or Read a source file — query the graph first for who-calls/where-used/impact questions (or rebuild if stale, build if absent). Source G’s strict block-first-read mode is deliberately un-ported.',
             ),
         }).default({}),
-        turn_end_gate: z.object({
-            enabled: z.boolean().default(false).describe(
-                'Stop-slot turn-end gate (road-to-conformance-round5 Phase 3). Default off, and it is the only concern that can REFUSE a turn-end rather than a tool call — so it soaks behind an explicit opt-in before it binds. Round 5 measured the reason: both blocking carriers reached zero violations, neither advisory carrier did, and 19 wrong-language replies survived a pin that had fired 26-35 seconds earlier. A refused turn continues in the SAME turn and is never refused twice.',
-            ),
-            promissory: z.boolean().default(true).describe(
-                'Detector A of the turn-end gate: refuse a turn whose closing paragraph promises work not yet performed while asking the user nothing (20 measured occurrences). No fire rate is quoted here on purpose: the measured rate moved twice while the instrument itself was being corrected, so a number in a shipped description would be a moving target. Re-derive it with `measure-turn-end-gate --store <transcript dir>` against your own corpus before arming the gate. Inert while hooks.turn_end_gate.enabled is false.',
-            ),
-            language: z.boolean().default(true).describe(
-                'Detector B of the turn-end gate: refuse a turn whose reply is not in the pinned language (19 measured occurrences). Fenced code, inline code, quoted tool output, tables, URLs and paths are stripped first, and the remainder is then scored LEAD-FIRST by the same classifier that sets the pin — so the verdict usually comes from the reply opening, not from all of it. Sharing that classifier is deliberate: it stops the pin and the detector disagreeing about a turn. Accepted opt-in spellings for the switches below include YAML true/false and yes/no/on/off. Inert while hooks.turn_end_gate.enabled is false.',
-            ),
-            verification: z.boolean().default(true).describe(
-                'Detector C of the turn-end gate: refuse a turn that changed a file and then ran nothing that could have checked it — no test, type-check, lint or build call follows the LAST edit. Ordering is the point: a run before the final edit did not exercise it, which is the freshness clause verify-before-complete states. Read off the turn tool calls, not the prose, because a reply cannot say whether an edit was verified. Deliberately narrow on what counts as verification — a missed detection costs one unguarded turn, a false refusal teaches you to switch the gate off. No fire rate is quoted: none has been measured yet. Inert while hooks.turn_end_gate.enabled is false.',
-            ),
-        }).default({}),
+        // `turn_end_gate` is deliberately ABSENT. The stop-slot turn-end gate is
+        // always armed (2026-08-12) and has no settings surface: whether it
+        // fires is decided by each detector's own trigger conditions, not by a
+        // flag. A leftover `hooks.turn_end_gate.*` block from an older install
+        // warns once on stderr and is ignored — see REMOVED_KEYS in
+        // `src/scripts/_lib/agent_settings.ts`.
     }),
     decision_engine: z.object({
         surface_traces: z.boolean().default(false).describe(