@event4u/agent-config 10.0.0 → 10.2.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/io/yamlIO.ts

@@ -144,8 +144,6 @@ export const TEMPLATE_PLACEHOLDER_DEFAULTS: Readonly<Record<string, string>> = {
     __DISCIPLINE_PROFILE__: 'auto',
     __USER_TYPE__: '',
     __CHAT_HISTORY_FREQUENCY__: 'per_turn',
-    __CHAT_HISTORY_MAX_SIZE_KB__: '2048',
-    __CHAT_HISTORY_ON_OVERFLOW__: 'rotate',
 };
 
 /** Replace every known template placeholder with its default value. */

package/src/server/schemas/settings.ts

@@ -21,7 +21,6 @@ const userType = z.enum(['', 'consultant', 'creator', 'developer', 'finance', 'f
 const profileId = z.enum(['developer', 'content_creator', 'founder', 'agency', 'finance', 'ops']);
 const accessStyle = z.enum(['getters_setters', 'get_attribute', 'magic_properties']);
 const chatFreq = z.enum(['per_turn', 'per_phase', 'per_tool']);
-const chatOverflow = z.enum(['rotate', 'condense']);
 const qualityCadence = z.enum(['end_of_roadmap', 'per_phase', 'per_step']);
 const regenCadence = z.enum(['per_step', 'every_5_steps', 'phase_boundary']);
 const worktreeMode = z.enum(['off', 'on', 'ask']);
@@ -169,12 +168,6 @@ export const settingsSchema = z.object({
         frequency: chatFreq.default('per_turn').describe(
             'How often the chat-history writer flushes to disk. per_turn = after every user / agent exchange (default, lowest data loss on crash). per_phase = at phase boundaries (cheaper I/O). per_tool = after every tool call (highest fidelity, noisiest log).',
         ),
-        max_size_kb: z.number().int().min(0).default(2048).describe(
-            'Maximum size (KB) of the active chat-history file before chat_history.on_overflow kicks in. Set 0 to disable rotation / condensation entirely (file grows forever).',
-        ),
-        on_overflow: chatOverflow.default('rotate').describe(
-            'What happens when chat_history.max_size_kb is hit. rotate = move the current log aside and start fresh (default). condense = telegraph-condense the oldest entries in place to keep recent context.',
-        ),
         text_limits: z.object({
             user: z.number().int().min(0).default(0).describe(
                 'Per-message character cap for user inputs in the chat-history log. 0 = log verbatim (default). Raise above 0 only if your prompts contain large pasted artefacts you do not want stored.',
@@ -231,9 +224,6 @@ export const settingsSchema = z.object({
         local_auto_run: z.boolean().default(false).describe(
             'Run quality tools (linters, type-checks, formatters) and the local test suite autonomously after edits. Off by default — the agent never runs quality tools proactively and does not ask; the user runs them manually (e.g. /quality-fix) and remote CI is the authoritative gate. The agent only runs a quality tool on an explicit ask, a concrete CI failure, or the new-gate carve-out. Turn on to restore autonomous pipeline runs.',
         ),
-        wait_for_remote_ci: z.boolean().default(false).describe(
-            'After pushing a branch, poll the remote CI provider (GitHub Actions, GitLab CI) and surface failures inline. Off by default — useful when local CI does not cover everything the remote pipeline runs.',
-        ),
     }),
     design: z.object({
         fidelity_mode: fidelityMode.default('strict').describe(
@@ -258,12 +248,9 @@ export const settingsSchema = z.object({
     }).default({ identity_allowlist: [], forbid_terminal_capture: true, data_bearing_gate: 'on' }),
     telegraph: z.object({
         speak: z.boolean().default(false).describe(
-            'Whether the telegraph-speak rule ships at all. false (default) = DORMANT: compile_router omits the rule from dist/router.json entirely, so its body never reaches a host. This — not speak_scope — is the lever that stops the cost. Set true only after an output-side bench clears the kill-criterion bar (docs/adrs/telegraph/0002).',
+            'Whether the telegraph-speak rule ships at all. false (default) = DORMANT: compile_router omits the rule from dist/router.json entirely, so its body never reaches a host. This is the only lever that stops the cost. Set true only after an output-side bench clears the kill-criterion bar (docs/adrs/telegraph/0002).',
         ),
-        speak_scope: z.enum(['off', 'reply', 'all']).default('off').describe(
-            "Where telegraph condensation applies WHEN speak is true. off (default) = agent reply prose is exempt. compile_router never reads this key: with speak false the rule does not ship, so this setting has no effect on its own. Quote the value in YAML — bare `off` parses as a boolean under YAML 1.1 and is rejected.",
-        ),
-    }).default({ speak: false, speak_scope: 'off' }),
+    }).default({ speak: false }),
     tokens: z.object({
         rich_skills: richSkillsMode.default('on').describe(
             'Whether skills marked token_budget_class: rich may load in full (exempt from telegraph-speak + thin-projector trimming), consumed by the token-budget-discipline rule. on = allowed (default); off = fall back to standard condensed behavior; ask = surface an estimated token delta (tokens, not dollars) and ask once per session before loading.',
@@ -573,13 +560,10 @@ export const settingsSchema = z.object({
         acknowledged: z.boolean().default(false).describe(
             'I understand the legal-review-prep pack provides templates and general information ONLY — it is NOT legal advice, creates no attorney-client relationship, and never replaces a licensed lawyer. Individual cases require an attorney. The pack stays inactive until this is checked.',
         ),
-        consented_at: z.string().default('').describe(
-            'ISO timestamp recorded when the legal-review-prep acknowledgment was given. Set automatically by the setup wizard; leave empty otherwise.',
-        ),
         require_council: z.boolean().default(true).describe(
             'Gate legal work-product behind a multi-model AI-council / deep-research pass (defense-in-depth: documented multi-stage review + audit trail; fail-closed when no council is configured). Leave on for the safest posture. Turning it off lets single-model legal output through — not recommended for a high-risk pack.',
         ),
-    }).default({ acknowledged: false, consented_at: '', require_council: true }),
+    }).default({ acknowledged: false, require_council: true }),
 });
 
 export type Settings = z.infer<typeof settingsSchema>;

package/src/shared/settingsClasses.ts

@@ -24,16 +24,61 @@ export function isSettingsClass(value: string): value is SettingsClass {
     return (SETTINGS_CLASSES as readonly string[]).includes(value);
 }
 
+/**
+ * The closed disposition vocabulary — the axis orthogonal to A/B/C.
+ *
+ * A/B/C answers *who may write a key*. This answers *whether the key should
+ * exist at all*, which is a different question with a different action per
+ * value. A row outside the vocabulary is a defect, not a new disposition.
+ */
+export const SETTINGS_DISPOSITIONS = ['derivable', 'un-inferrable', 'consent', 'policy'] as const;
+
+export type SettingsDisposition = (typeof SETTINGS_DISPOSITIONS)[number];
+
+export function isSettingsDisposition(value: string): value is SettingsDisposition {
+    return (SETTINGS_DISPOSITIONS as readonly string[]).includes(value);
+}
+
 /** One parsed row of the contract's key table. */
 export interface SettingsClassRow {
     /** Dotted leaf path, e.g. `personal.autonomy`. */
     key: string;
     /** Raw class cell — NOT yet validated, so the lint can report a bad one. */
     cls: string;
+    /**
+     * Raw disposition cell, or `null` when the row has no fifth column at all.
+     *
+     * NOT validated here, for the same reason `cls` is not: the lint has to be
+     * able to report a bad value, and a parser that silently drops it would
+     * make an unclassified key indistinguishable from a mis-spelled one.
+     *
+     * `derivable` rows carry their replacement after an em dash — the clause
+     * that makes the label falsifiable rather than a synonym for "inconvenient
+     * to keep". `dispositionOf` returns the label, `replacementOf` the clause.
+     */
+    disposition: string | null;
     /** 1-indexed line in the contract, so a finding points at something. */
     line: number;
 }
 
+/** `derivable — the detector's own trigger condition` → `derivable`. */
+export function dispositionOf(cell: string | null): string | null {
+    if (cell === null) {
+        return null;
+    }
+    const [label] = cell.split('—');
+    return (label ?? '').trim();
+}
+
+/** `derivable — the detector's own trigger condition` → the clause after the dash. */
+export function replacementOf(cell: string | null): string {
+    if (cell === null) {
+        return '';
+    }
+    const dash = cell.indexOf('—');
+    return dash === -1 ? '' : cell.slice(dash + 1).trim();
+}
+
 /** What the contract's own `## Counts` table claims about itself. */
 export interface DeclaredClassCounts {
     A: number | null;
@@ -51,11 +96,20 @@ export interface DeclaredClassCounts {
  */
 const ROW_RE = /^\|\s*`([^`]+)`\s*\|\s*([^|]*?)\s*\|/;
 
+/**
+ * The disposition is read as the FIFTH cell, appended after `Why`, so the four
+ * cells every existing consumer indexes keep their positions. A row that
+ * predates the axis simply has no fifth cell and parses to `null` — an absent
+ * disposition, which the lint reports, rather than a shifted `Default`.
+ */
+const DISPOSITION_RE = /^\|\s*`[^`]+`\s*\|[^|]*\|[^|]*\|[^|]*\|\s*([^|]*?)\s*\|/;
+
 export function parseSettingsClassRows(markdown: string): SettingsClassRow[] {
     const rows: SettingsClassRow[] = [];
     const lines = markdown.split('\n');
     for (let i = 0; i < lines.length; i++) {
-        const m = ROW_RE.exec(lines[i] ?? '');
+        const line = lines[i] ?? '';
+        const m = ROW_RE.exec(line);
         if (m === null) {
             continue;
         }
@@ -64,7 +118,9 @@ export function parseSettingsClassRows(markdown: string): SettingsClassRow[] {
         if (!/^[A-Za-z]$/.test(cls)) {
             continue;
         }
-        rows.push({ key, cls, line: i + 1 });
+        const d = DISPOSITION_RE.exec(line);
+        const raw = d?.[1] ?? '';
+        rows.push({ key, cls, disposition: raw === '' ? null : raw, line: i + 1 });
     }
     return rows;
 }
@@ -84,6 +140,41 @@ export function parseDeclaredClassCounts(markdown: string): DeclaredClassCounts
     };
 }
 
+/** What the contract's own `## Dispositions` table claims about itself. */
+export interface DeclaredDispositionCounts {
+    derivable: number | null;
+    'un-inferrable': number | null;
+    consent: number | null;
+    policy: number | null;
+    total: number | null;
+}
+
+/** `| derivable | 12 |` and `| **Total** | **140** |` under `## Dispositions`. */
+export function parseDeclaredDispositionCounts(markdown: string): DeclaredDispositionCounts {
+    // Scoped to the section, so the class Counts table's own **Total** row —
+    // identical in shape and earlier in the file — cannot be read as this one.
+    const start = markdown.indexOf('\n## Dispositions');
+    const section = start === -1 ? '' : markdown.slice(start + 1);
+    const end = section.indexOf('\n## ', 1);
+    const scoped = end === -1 ? section : section.slice(0, end);
+    // The value cell is read with optional `**` so the bolded `**Total**` row
+    // and the plain per-label rows go through one path — a second regex for the
+    // total is a second thing to get wrong.
+    const read = (label: string): number | null => {
+        const re = new RegExp(String.raw`^\|\s*` + label + String.raw`\s*\|\s*\**(\d+)\**\s*\|`, 'm');
+        const m = re.exec(scoped);
+        const raw = m?.[1];
+        return raw === undefined ? null : Number.parseInt(raw, 10);
+    };
+    return {
+        derivable: read('derivable'),
+        'un-inferrable': read('un-inferrable'),
+        consent: read('consent'),
+        policy: read('policy'),
+        total: read(String.raw`\*\*Total\*\*`),
+    };
+}
+
 /**
  * Dotted key → class, for the rows whose class is valid.
  *