@event4u/agent-config 7.4.0 → 8.0.0

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

@@ -0,0 +1,106 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/subagent.schema.json",
+  "title": "Subagent frontmatter (subagent-v1)",
+  "$comment": "Source: ADR-109. A subagent is an addressable, tool-scoped execution context projected to a host's native subagent format (Claude Code `.claude/agents/`) or, on non-subagent hosts, to a loadable context file. Static projection only — dispatch stays with the host/user, never runtime-enforced. Governance fields (trust, lifecycle, discovery.visible) are REQUIRED, mirroring the skill trust block so subagents share one governance model. model_tier reuses model_tier.ts (ADR-034/035).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "name",
+    "description",
+    "model_tier",
+    "tools",
+    "trust",
+    "lifecycle",
+    "discovery",
+    "source"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "subagent-v1"
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Addressable handle. Must match the subagent filename stem and be globally unique within the subagent category (projection-path collision guard)."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240,
+      "description": "User-facing summary. On Claude Code this drives `@`-menu discoverability; keep it action-oriented."
+    },
+    "model_tier": {
+      "type": "string",
+      "enum": ["lite", "medium", "high", "inherit"],
+      "description": "Vendor-neutral capability band (ADR-034/035). high/medium/lite project to a native Claude `model:` (high→opus, medium→sonnet, lite→haiku) via model_tier.ts; `inherit` is a documented passthrough sentinel (→ CC `model: inherit`), not a new mapping."
+    },
+    "tools": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": ["Read", "Write", "Edit", "Grep", "Glob", "Bash", "WebFetch", "WebSearch", "NotebookEdit"]
+      },
+      "description": "Enum-validated at build time against the Claude Code tool set, so a bad value fails CI rather than producing broken `.claude/agents/` YAML in the user's IDE."
+    },
+    "trust": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["level", "confidence", "human_review_required"],
+      "properties": {
+        "level": {
+          "type": "string",
+          "enum": ["core", "professional", "experimental", "advisory", "restricted"],
+          "default": "core"
+        },
+        "confidence": {
+          "type": "string",
+          "enum": ["high", "medium", "low"],
+          "default": "high"
+        },
+        "human_review_required": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      "description": "ADR-013 trust block, mirrored from the skill schema so subagents share one governance model."
+    },
+    "lifecycle": {
+      "type": "string",
+      "enum": ["active", "deprecated", "experimental", "archived"],
+      "default": "active",
+      "description": "ADR-013 lifecycle state."
+    },
+    "discovery": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["visible", "requires_capability"],
+      "properties": {
+        "visible": {
+          "const": false,
+          "description": "Subagents are default-off. The value MUST be false; a pack/profile opts in explicitly via include: [\"subagent:<name>\"]."
+        },
+        "requires_capability": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Host-capability gate (e.g. claude_subagents). Hosts without the capability receive the loadable-context-file degradation, not native dispatch."
+        },
+        "categories": {
+          "type": "array",
+          "items": { "type": "string" },
+          "uniqueItems": true,
+          "description": "Optional pack-include tags (include: [\"subagent:category:<tag>\"])."
+        }
+      }
+    },
+    "source": {
+      "type": "string",
+      "enum": ["package", "project"],
+      "default": "package"
+    }
+  }
+}

package/src/scripts/skill_linter.ts

@@ -1428,6 +1428,7 @@ export function lint_skill(p: string, text: string): LintResult {
             'terragrunt',
             'traefik',
             'websocket',
+            'wireframe',
         ]);
         if (!ALLOWED_BARE_NOUNS.has(skillName.toLowerCase())) {
             issues.push(

package/src/scripts/smoke/kernel.sh

@@ -2,9 +2,10 @@
 # scripts/smoke/kernel.sh — kernel-tier smoke (step-11 Phase 3 Step 2).
 #
 # Asserts:
-#   1. router.json lists exactly 10 kernel rules.
+#   1. router.json lists exactly 9 kernel rules.
 #   2. Every kernel rule file exists at dist/agent-src/rules/<id>.md.
-#   3. 9 of 10 carry at least one Iron-Law fenced block.
+#   3. 8 of 9 carry at least one Iron-Law fenced block (agent-authority
+#      is the fence-less priority index).
 #      agent-authority is the dispatch index, exempt from the fence
 #      requirement (docs/contracts/smoke-contracts.md § 3.1).
 #   4. Kernel-bucket char budget breaches ≤ EXPECTED_BREACHES.
@@ -16,8 +17,8 @@
 
 set -euo pipefail
 
-EXPECTED_KERNEL_COUNT=10
-EXPECTED_FENCE_CARRIERS=9
+EXPECTED_KERNEL_COUNT=9
+EXPECTED_FENCE_CARRIERS=8
 # Bumped 2 → 3 in v4.0.0: the `fix(authority): block execution offers
 # after roadmap/vision artifact save` commit (d30d441e) pushed
 # scope-control and commit-policy past their per-rule caps; kernel-bucket

package/src/scripts/surface-tiers.yml

@@ -37,6 +37,7 @@ clusters:
   cost: lab              # cost tracking / budget gate (observability, Node .mjs)
   mcp_server: lab        # MCP stdio server, separate runtime, pilot distribution
   media: lab             # shared adapter substrate for ai-video / ai-image
+  parity: lab            # py2ts parity rigs (compare / coverage-diff), migration tooling
   prediction-pool: lab   # prediction-pool optimizer (fun pack, experimental)
 
 # Top-level src/scripts/*.py modules that belong to lab (module stem, no .py).

package/src/scripts/sync_gitignore.ts

@@ -55,6 +55,10 @@ export const DEFAULT_TEMPLATE = path.join(
 // managed block or outside (older installers / hand-edits). Current canonical
 // equivalents (e.g. /agents/runtime/.agent-prices.md) come from the template
 // and are NOT affected. Leading-slash variants are matched defensively.
+//
+// Authoritative source: src/config/agents-paths.yml entries with `legacy: true`.
+// Manual sync until the generation step from the manifest is implemented
+// (road-to-agents-dir-and-gitignore-hygiene Phase 3.2 follow-on).
 export const LEGACY_PATTERNS: readonly string[] = [
     '.agent-chat-history',
     '.agent-chat-history.bak',

package/src/scripts/update_skill_candidates.ts

@@ -0,0 +1,172 @@
+#!/usr/bin/env tsx
+/**
+ * Cross-cycle recurrence tracker for `agents/knowledge/procedures/skill-candidates.md`
+ * — road-to-knowledge-system Phase 2 (capture hygiene).
+ *
+ * Each `/memory:mine-session` / `memory-consolidation` cycle that finds an
+ * unpromoted, recurring topic calls this to increment a durable per-topic
+ * counter. At >= 3 mentions the topic is a live skill/procedure candidate —
+ * `learning-to-rule-or-skill` picks it up from here for human-gated
+ * promotion. This script only maintains the counter file; it never proposes
+ * or writes a skill/rule itself.
+ *
+ * Usage:
+ *   update_skill_candidates.ts --topic <slug> --session <id> --date <YYYY-MM-DD> [--file <path>]
+ *
+ * Exit codes: 0 = updated (prints whether the candidate threshold (3) was
+ * crossed BY this call), 1 = usage error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const PROG = 'update_skill_candidates.ts';
+export const CANDIDATE_THRESHOLD = 3;
+const DEFAULT_FILE = path.join('agents', 'knowledge', 'procedures', 'skill-candidates.md');
+
+export interface CandidateRecord {
+    topic: string;
+    mentions: number;
+    first: string; // YYYY-MM-DD
+    lastSeen: string; // YYYY-MM-DD
+    sessions: string[]; // unique, insertion order
+}
+
+const HEADING_RE = /^## (.+)$/;
+const FIELD_RE = /^- (\w[\w ]*): (.*)$/;
+
+/** Parse the skill-candidates.md body into topic → record. Tolerant of a missing/empty file. */
+export function parseCandidates(body: string): Map<string, CandidateRecord> {
+    const out = new Map<string, CandidateRecord>();
+    let current: CandidateRecord | null = null;
+
+    for (const rawLine of body.split(/\r?\n/)) {
+        const headingMatch = HEADING_RE.exec(rawLine);
+        if (headingMatch?.[1] !== undefined) {
+            current = { topic: headingMatch[1].trim(), mentions: 0, first: '', lastSeen: '', sessions: [] };
+            out.set(current.topic, current);
+            continue;
+        }
+        if (!current) continue;
+        const fieldMatch = FIELD_RE.exec(rawLine);
+        if (!fieldMatch) continue;
+        const [, key, value] = fieldMatch;
+        if (key === undefined || value === undefined) continue;
+        if (key === 'Mentions') current.mentions = Number.parseInt(value, 10) || 0;
+        else if (key === 'First seen') current.first = value.trim();
+        else if (key === 'Last seen') current.lastSeen = value.trim();
+        else if (key === 'Sessions') {
+            current.sessions = value
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean);
+        }
+    }
+    return out;
+}
+
+export function renderCandidates(records: Map<string, CandidateRecord>): string {
+    const lines: string[] = [];
+    lines.push('# Skill Candidates');
+    lines.push('');
+    lines.push(
+        `_Auto-maintained by \`src/scripts/update_skill_candidates.ts\`. A topic reaches candidate status at ${CANDIDATE_THRESHOLD}+ mentions across distinct sessions — see \`learning-to-rule-or-skill\` for the human-gated promotion path._`,
+    );
+
+    const topics = [...records.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    for (const topic of topics) {
+        const r = records.get(topic)!;
+        lines.push('');
+        lines.push(`## ${r.topic}`);
+        lines.push('');
+        lines.push(`- Mentions: ${r.mentions}`);
+        lines.push(`- First seen: ${r.first}`);
+        lines.push(`- Last seen: ${r.lastSeen}`);
+        lines.push(`- Sessions: ${r.sessions.join(', ')}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+
+/** Increment (or create) a topic's recurrence record. Mutates and returns the map; returns whether this call crossed the candidate threshold. */
+export function upsertCandidate(
+    records: Map<string, CandidateRecord>,
+    topic: string,
+    sessionId: string,
+    date: string,
+): { crossedThreshold: boolean; record: CandidateRecord } {
+    let record = records.get(topic);
+    const wasBelowThreshold = !record || record.mentions < CANDIDATE_THRESHOLD;
+
+    if (!record) {
+        record = { topic, mentions: 0, first: date, lastSeen: date, sessions: [] };
+        records.set(topic, record);
+    }
+
+    if (!record.sessions.includes(sessionId)) {
+        record.sessions.push(sessionId);
+        record.mentions += 1;
+    }
+    record.lastSeen = date;
+
+    const crossedThreshold = wasBelowThreshold && record.mentions >= CANDIDATE_THRESHOLD;
+    return { crossedThreshold, record };
+}
+
+function printUsage(): void {
+    process.stderr.write(`usage: ${PROG} --topic TOPIC --session ID --date YYYY-MM-DD [--file PATH]\n`);
+}
+
+export function main(argv: string[]): number {
+    let topic: string | null = null;
+    let session: string | null = null;
+    let date: string | null = null;
+    let file = DEFAULT_FILE;
+
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h' || arg === '--help') {
+            printUsage();
+            return 0;
+        } else if (arg === '--topic') {
+            topic = argv[++i] ?? null;
+        } else if (arg === '--session') {
+            session = argv[++i] ?? null;
+        } else if (arg === '--date') {
+            date = argv[++i] ?? null;
+        } else if (arg === '--file') {
+            file = argv[++i] ?? file;
+        } else {
+            process.stderr.write(`${PROG}: error: unrecognized argument: ${arg}\n`);
+            printUsage();
+            return 1;
+        }
+    }
+
+    if (!topic || !session || !date) {
+        process.stderr.write(`${PROG}: error: --topic, --session, and --date are required\n`);
+        printUsage();
+        return 1;
+    }
+
+    const existingBody = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    const records = parseCandidates(existingBody);
+    const { crossedThreshold, record } = upsertCandidate(records, topic, session, date);
+
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, renderCandidates(records), 'utf8');
+
+    if (crossedThreshold) {
+        process.stdout.write(
+            `${PROG}: "${topic}" reached candidate status (${record.mentions} mentions) — surface for learning-to-rule-or-skill.\n`,
+        );
+    } else {
+        process.stdout.write(`${PROG}: "${topic}" now at ${record.mentions} mention(s).\n`);
+    }
+    return 0;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/validate_frontmatter.ts

@@ -816,6 +816,7 @@ export function _iter_artefacts(root: string): Array<[string, string]> {
         ['skill', _rglobSorted(path.join(root, 'skills'), 'SKILL.md')],
         ['rule', _rglobSorted(path.join(root, 'rules'), '*.md')],
         ['command', _rglobSorted(path.join(root, 'commands'), '*.md')],
+        ['subagent', _rglobSorted(path.join(root, 'subagents'), '*.md')],
         [
             'persona',
             _globSorted(path.join(root, 'personas'), '*.md').filter(