@event4u/agent-config 9.2.0 → 9.4.0

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

@@ -6,7 +6,12 @@
   "$comment": "Source: agents/reference/docs/frontmatter-contract.md#skills. Keep in sync with inventory_frontmatter.py and the linter's lint_skill().",
   "type": "object",
   "additionalProperties": false,
-  "required": ["name", "description", "source", "domain"],
+  "required": [
+    "name",
+    "description",
+    "source",
+    "domain"
+  ],
   "properties": {
     "name": {
       "type": "string",
@@ -28,19 +33,41 @@
       "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."
     },
+    "provenance": {
+      "type": "string",
+      "enum": [
+        "official",
+        "community"
+      ],
+      "description": "Catalog source attribution: absent or 'official' = maintainer-authored; 'community' = merged external contribution (credited in CREDITS.md; rendered in the catalog's source column)."
+    },
     "source": {
       "type": "string",
-      "enum": ["package", "project"],
+      "enum": [
+        "package",
+        "project"
+      ],
       "default": "package"
     },
     "domain": {
       "type": "string",
-      "enum": ["engineering", "product", "quality", "devops", "process", "discovery"],
+      "enum": [
+        "engineering",
+        "product",
+        "quality",
+        "devops",
+        "process",
+        "discovery"
+      ],
       "description": "Skill classification axis; see docs/contracts/skill-domains.md. Required for every skill — exactly one of: engineering, product, quality, devops, process, discovery."
     },
     "status": {
       "type": "string",
-      "enum": ["active", "deprecated", "superseded"]
+      "enum": [
+        "active",
+        "deprecated",
+        "superseded"
+      ]
     },
     "replaced_by": {
       "type": "string",
@@ -60,7 +87,9 @@
     },
     "tier": {
       "type": "string",
-      "enum": ["senior"],
+      "enum": [
+        "senior"
+      ],
       "description": "Optional tier marker. `senior` opts the skill into the Senior-Tier Required Structure check (Context-First lead, Related Skills, Proactive Triggers, Output Artifacts) per .agent-src.uncondensed/rules/skill-quality.md."
     },
     "meta_skill": {
@@ -84,23 +113,37 @@
     },
     "model_tier": {
       "type": "string",
-      "enum": ["lite", "medium", "high", "inherit"],
+      "enum": [
+        "lite",
+        "medium",
+        "high",
+        "inherit"
+      ],
       "description": "Vendor-neutral capability band the skill needs (ADR-035). high/medium/lite project to a native Claude `model:` (high→opus, medium→sonnet, lite→haiku) when model.auto_switch=auto; the generator owns that mapping exclusively. inherit keeps the session model. Non-Claude agents are suggestion-only — the model-recommendation rule names the tier and the agent resolves its own model. No vendor model names here."
     },
     "context": {
       "type": "string",
-      "enum": ["large"],
+      "enum": [
+        "large"
+      ],
       "description": "Optional orthogonal modifier (ADR-035): the skill needs a large-context model regardless of reasoning tier (e.g. summarising a 500-page log). Sparse — most skills omit it. Metadata only; does not change the native Claude `model:` (the tier owns the model choice)."
     },
     "effort": {
       "type": "string",
-      "enum": ["low", "medium", "high", "max"],
+      "enum": [
+        "low",
+        "medium",
+        "high",
+        "max"
+      ],
       "description": "Optional pinned reasoning-effort level for hosts with an effort knob (Claude Code `--effort` / agent frontmatter). Passthrough: skills project verbatim, so the key reaches Claude Code as-is and is inert on hosts without the knob. The bench harness pins it per run (bench_ab_task_runner `--effort`) so measurements are reproducible. Orthogonal to `model_tier` (capability band) — effort tunes how hard the model thinks, not which model runs. Omit unless the skill measurably needs a non-default effort.",
       "$comment": "road-to-ecosystem-harvest-skill-quality-gates Phase 4, Source S (pinned effort frontmatter)."
     },
     "council_depth": {
       "type": "string",
-      "enum": ["deep"],
+      "enum": [
+        "deep"
+      ],
       "description": "Optional reasoning-depth marker for AI Council invocations triggered by this skill. The only accepted value is 'deep'; omit the key for default depth (setting 'standard' is rejected — every frontmatter byte counts against the context window, and 'standard' is the implicit default). 'deep' instructs the host agent to pass --depth deep to council_cli, which floors rounds at max(ai_council.deep_min_rounds, ai_council.min_rounds). Use for architecture, refactoring, or bug-diagnosis skills. See .agent-src.uncondensed/skills/ai-council/SKILL.md."
     },
     "context_spine": {
@@ -108,28 +151,52 @@
       "uniqueItems": true,
       "items": {
         "type": "string",
-        "enum": ["product", "team", "repo", "channel-stage", "funnel-stage", "customer-segment", "fiscal-period", "org-stage", "regulatory-regime"]
+        "enum": [
+          "product",
+          "team",
+          "repo",
+          "channel-stage",
+          "funnel-stage",
+          "customer-segment",
+          "fiscal-period",
+          "org-stage",
+          "regulatory-regime"
+        ]
       },
       "description": "Senior-skill opt-in for the context spine. Declares which slots under agents/context-spine/ the skill expects to read. Cross-wing slots (product, team, repo) are locked at 3 by council Q1 (KEEP-3); wing-scoped slots follow the per-wing ADR track in docs/contracts/context-spine.md § 5. Wing-3 (channel-stage, funnel-stage, customer-segment) authorized by docs/contracts/adr-gtm-context-spine.md; Wing-4 (fiscal-period, org-stage, regulatory-regime) authorized by docs/contracts/adr-wing4-context-spine.md."
     },
     "recommended_for_user_types": {
       "type": "array",
       "uniqueItems": true,
-      "items": {"type": "string"},
+      "items": {
+        "type": "string"
+      },
       "description": "Forward-compatible user-type recommendation tags (step-12-universal-os-reframe Phase 5). Skill loads for every user-type whose slug appears in this list. Absence of the key marks the skill as universal — see docs/contracts/universal-skills.md for the always-loaded floor and docs/contracts/router-blending.md for per-user-type mix ratios. Wired by step-9-user-types-axis once it lands; treated as metadata until then. Free-form tags (e.g. 'creator', 'founder', 'consultant', 'gtm', 'finance', 'ops', 'developer') — no enum until the user-types axis closes."
     },
     "execution": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["type"],
+      "required": [
+        "type"
+      ],
       "properties": {
         "type": {
           "type": "string",
-          "enum": ["manual", "assisted", "automated"]
+          "enum": [
+            "manual",
+            "assisted",
+            "automated"
+          ]
         },
         "handler": {
           "type": "string",
-          "enum": ["none", "shell", "php", "node", "internal"]
+          "enum": [
+            "none",
+            "shell",
+            "php",
+            "node",
+            "internal"
+          ]
         },
         "timeout_seconds": {
           "type": "integer",
@@ -137,22 +204,30 @@
         },
         "safety_mode": {
           "type": "string",
-          "enum": ["strict"]
+          "enum": [
+            "strict"
+          ]
         },
         "allowed_tools": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": {
+            "type": "string"
+          },
           "description": "Allow-list of tool grants. Prefer the scoped-grant syntax over bare tool names where the host supports it — e.g. Bash(npm test:*) instead of Bash — per tool-safety Least Agency."
         },
         "disallowed_tools": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": {
+            "type": "string"
+          },
           "description": "U3 (ecosystem harvest): optional deny-list layered UNDER allowed_tools — defense-in-depth; a tool matching here is refused even if a broad allow pattern would admit it. Supports the scoped-grant syntax (e.g. Bash(git push:*))."
         },
         "command": {
           "type": "array",
           "minItems": 1,
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         }
       }
     },
@@ -160,19 +235,30 @@
       "type": "array",
       "minItems": 1,
       "uniqueItems": true,
-      "items": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$"
+      },
       "description": "ADR-013 workspace ids (additive discovery axis). Closed vocabulary enforced by scripts/lint_artefact_frontmatter.py against config/discovery/workspaces.yml."
     },
     "packs": {
       "type": "array",
       "minItems": 1,
       "uniqueItems": true,
-      "items": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$"
+      },
       "description": "ADR-013 pack ids (additive discovery axis). Closed vocabulary enforced by scripts/lint_artefact_frontmatter.py against config/discovery/packs.yml."
     },
     "lifecycle": {
       "type": "string",
-      "enum": ["active", "deprecated", "experimental", "archived"],
+      "enum": [
+        "active",
+        "deprecated",
+        "experimental",
+        "archived"
+      ],
       "default": "active",
       "description": "ADR-013 lifecycle state."
     },
@@ -180,38 +266,83 @@
       "type": "array",
       "minItems": 1,
       "uniqueItems": true,
-      "items": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$"
+      },
       "description": "Skill-composition graph (roadmap 3.4): names of sub-skills this skill's body invokes/assumes. Distinct from ADR-015 `requires` (artefact→pack edges). scripts/check_skill_requires.py enforces (a) each target exists and (b) the required skill is co-available wherever this skill ships (same pack, a requires_hint-reachable pack, or always-on)."
     },
     "trust": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["level", "confidence", "human_review_required"],
+      "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}
+        "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. Vocabulary mirrored by scripts/lint_artefact_frontmatter.py."
     },
     "install": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["default", "removable"],
+      "required": [
+        "default",
+        "removable"
+      ],
       "properties": {
-        "default": {"type": "boolean", "default": true},
-        "removable": {"type": "boolean", "default": false}
+        "default": {
+          "type": "boolean",
+          "default": true
+        },
+        "removable": {
+          "type": "boolean",
+          "default": false
+        }
       },
       "description": "ADR-013 install hints (default-on at consumer install; user-removable)."
     },
     "token_budget_class": {
       "type": "string",
-      "enum": ["lean", "standard", "rich"],
+      "enum": [
+        "lean",
+        "standard",
+        "rich"
+      ],
       "description": "Token-cost class for this skill. `lean` (default): subject to telegraph-speak condensation and thin-projector trimming; optimize for <500 tokens. `standard`: balanced guidance, normal condensation. `rich`: exempt from telegraph-speak and thin-projector trimming; detailed examples preserved; eager-load eligible; ≤15% of skills in a suite may be `rich` (CI-enforced). A `rich` skill MUST carry a '## Why this skill is rich' section explaining the irreducible complexity that makes condensation harmful. Governed by `token-budget-discipline` rule + `tokens.rich_skills` consumer setting. See docs/guidelines/token-budget-governance.md."
     },
     "parallelizable": {
       "type": "string",
-      "enum": ["steps", "files", "independent"],
+      "enum": [
+        "steps",
+        "files",
+        "independent"
+      ],
       "description": "Classifier signal for auto-dispatch. 'steps' = ordered multi-step plan → do-in-steps. 'files' = N independent files of the same shape → do-in-parallel. 'independent' = N independent same-shape targets (not files) → do-in-parallel. Omit for skills that are always single-pass. Read by auto-dispatch-classification.md classifier signal 1."
     },
     "gaps": {
@@ -220,7 +351,10 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["description", "witness"],
+        "required": [
+          "description",
+          "witness"
+        ],
         "properties": {
           "description": {
             "type": "string",

package/src/scripts/self_review_gate.test.ts

@@ -1,7 +1,9 @@
 import { describe, expect, it } from 'vitest';
 
 import {
+    LARGE_DIFF_LINES,
     classifyBlocking,
+    escalationReasons,
     gateVerdict,
     isReviewablePath,
     renderReview,
@@ -74,3 +76,49 @@ describe('renderReview', () => {
         expect((out.match(/\(Blocking\)/g) ?? []).length).toBe(1);
     });
 });
+
+describe('escalationReasons', () => {
+    it('flags a large diff at or above the threshold', () => {
+        expect(escalationReasons(['src/a.ts'], LARGE_DIFF_LINES)).toEqual([
+            `large diff (${LARGE_DIFF_LINES} changed lines ≥ ${LARGE_DIFF_LINES})`,
+        ]);
+    });
+    it('does not flag a small non-claim diff', () => {
+        expect(escalationReasons(['src/a.ts'], LARGE_DIFF_LINES - 1)).toEqual([]);
+    });
+    it('flags a claim-ledger surface regardless of size', () => {
+        expect(escalationReasons(['docs/CLAIMS.md'], 1)).toEqual([
+            'claim-affecting surface touched (docs/CLAIMS.md)',
+        ]);
+        expect(escalationReasons(['docs/proof.md'], 1)[0]).toContain('docs/proof.md');
+        expect(escalationReasons(['docs/comparison.yaml'], 1)[0]).toContain('docs/comparison.yaml');
+        expect(escalationReasons(['README.md'], 1)[0]).toContain('README.md');
+    });
+    it('reports both reasons when a large diff also touches a claim surface', () => {
+        const r = escalationReasons(['docs/CLAIMS.md', 'src/big.ts'], LARGE_DIFF_LINES + 50);
+        expect(r).toHaveLength(2);
+        expect(r[0]).toContain('large diff');
+        expect(r[1]).toContain('claim-affecting');
+    });
+});
+
+describe('renderReview — escalation banner', () => {
+    const f = (severity: Finding['severity'], kind: Finding['kind']): Finding => ({
+        severity, kind, title: 't', detail: 'd',
+    });
+    it('appends the escalation recommendation when reasons are present', () => {
+        const out = renderReview([], false, ['large diff (500 changed lines ≥ 400)']);
+        expect(out).toContain('Escalation warranted');
+        expect(out).toContain('/council:pr');
+        expect(out).toContain('never');
+    });
+    it('omits the escalation block when there are no reasons (byte-identical to no-arg)', () => {
+        const findings = [f('high', 'security')];
+        expect(renderReview(findings, false, [])).toBe(renderReview(findings, false));
+    });
+    it('recommends escalation even on a clean (no-finding) large diff', () => {
+        const out = renderReview([], false, ['large diff (500 changed lines ≥ 400)']);
+        expect(out).toContain('no findings');
+        expect(out).toContain('Escalation warranted');
+    });
+});

package/src/scripts/self_review_gate.ts

@@ -12,6 +12,14 @@
  *     advisory mode it NEVER blocks the merge (exit 0) — it records what WOULD
  *     block. If no key is available it is a logged no-op (exit 0), never a failure.
  *
+ * On a LARGE or CLAIM-AFFECTING diff the two in-session lenses are not enough —
+ * such a diff warrants the full `ai-council` advisor panel. That is a
+ * spend-bearing multi-model run, so per blocker `self-review-gate-cost` the gate
+ * DETECTS the escalation deterministically (`escalationReasons`) and RECOMMENDS
+ * a maintainer `/council:pr` run; it never fires paid council calls itself. The
+ * paid council stays governed by the standing spend-authorization discipline at
+ * run time.
+ *
  * Turning the gate REQUIRED (block-on-verdict) and wiring the API secret + the
  * per-PR budget are the maintainer's acts (blocker `self-review-gate-cost`); this
  * script exposes the `--enforce` path so that flip is a one-flag change, but the
@@ -100,6 +108,47 @@ function diffText(baseRef: string, files: string[]): string {
     return (r.stdout ?? '').toString();
 }
 
+/** Sum of added+deleted lines across `files` (binary files count 0). */
+function changedLineCount(baseRef: string, files: string[]): number {
+    if (files.length === 0) return 0;
+    const r = spawnSync('git', ['diff', '--numstat', `${baseRef}...HEAD`, '--', ...files], {
+        cwd: REPO_ROOT,
+        encoding: 'utf8',
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    let total = 0;
+    for (const line of (r.stdout ?? '').toString().split('\n')) {
+        const m = /^(\d+)\t(\d+)\t/.exec(line); // added \t deleted \t path ("-" for binary)
+        if (m) total += Number(m[1]) + Number(m[2]);
+    }
+    return total;
+}
+
+// ── Escalation classifier (large / claim-affecting → full ai-council) ──
+/**
+ * A large or claim-affecting diff warrants the FULL `ai-council` (advisor
+ * panel), not just the two in-session lenses — but that is a spend-bearing,
+ * multi-model run. Per blocker `self-review-gate-cost` the paid council stays
+ * governed by the standing spend-authorization discipline AT RUN TIME: the gate
+ * DETECTS the escalation deterministically here and RECOMMENDS a maintainer
+ * `/council:pr` run; it never fires paid council calls by surprise in CI.
+ */
+export const LARGE_DIFF_LINES = 400;
+/** The claim ledger + proof surfaces `check_claims` binds to. */
+const CLAIM_SURFACES = new Set(['docs/CLAIMS.md', 'docs/proof.md', 'docs/comparison.yaml']);
+
+export function escalationReasons(files: readonly string[], changedLines: number): string[] {
+    const reasons: string[] = [];
+    if (changedLines >= LARGE_DIFF_LINES) {
+        reasons.push(`large diff (${changedLines} changed lines ≥ ${LARGE_DIFF_LINES})`);
+    }
+    const claimHits = files.filter((f) => CLAIM_SURFACES.has(f) || f === 'README.md');
+    if (claimHits.length > 0) {
+        reasons.push(`claim-affecting surface touched (${claimHits.join(', ')})`);
+    }
+    return reasons;
+}
+
 // ── Review skill bodies (the system prompt) ───────────────────────────
 const REVIEW_SKILLS = ['adversarial-review', 'agent-security-review'] as const;
 
@@ -129,15 +178,18 @@ export interface ReviewPlan {
     files: string[];
     promptChars: number;
     note: string;
+    escalation: string[];
 }
 
 export function buildPlan(baseRef: string): ReviewPlan {
     const files = changedFiles(baseRef);
     const diff = diffText(baseRef, files);
+    const escalation = escalationReasons(files, changedLineCount(baseRef, files));
     return {
         skills: [...REVIEW_SKILLS],
         files,
         promptChars: buildSystemPrompt().length + diff.length,
+        escalation,
         note:
             files.length === 0
                 ? 'No reviewable (non-generated) files changed — the live review would no-op.'
@@ -174,13 +226,26 @@ function parseFindings(text: string): Finding[] {
         }));
 }
 
-export function renderReview(findings: Finding[], enforce: boolean): string {
+/** Advisory escalation banner, appended when a diff warrants full ai-council. */
+function escalationBlock(reasons: readonly string[]): string {
+    if (reasons.length === 0) return '';
+    return (
+        `\n\n🔺 **Escalation warranted** — ${reasons.join('; ')}. The two in-session ` +
+        'lenses above are a floor; a maintainer should run the full `ai-council` ' +
+        '(`/council:pr`) on this diff. That is a spend-bearing, run-time-authorized ' +
+        'act (blocker `self-review-gate-cost`) — this gate recommends it, never ' +
+        'fires paid council calls itself.'
+    );
+}
+
+export function renderReview(findings: Finding[], enforce: boolean, escalation: readonly string[] = []): string {
     const banner =
         '> HUMAN REVIEW REQUIRED — dogfooded AI adversarial-review + security gate. ' +
         'Findings are decision support, not a guarantee; detection is probabilistic. ' +
         'This is a floor, **not** independent human review.';
+    const esc = escalationBlock(escalation);
     if (findings.length === 0) {
-        return `${banner}\n\n✅ Self-review gate: no findings.`;
+        return `${banner}\n\n✅ Self-review gate: no findings.${esc}`;
     }
     const blocking = findings.filter(classifyBlocking);
     // Each row carries an explicit (Blocking)/(Advisory) marker so a
@@ -197,7 +262,7 @@ export function renderReview(findings: Finding[], enforce: boolean): string {
             ? `❌ ${blocking.length} merge-blocking finding(s) (security/claim × high+).`
             : `⚠️ ${blocking.length} finding(s) WOULD block merge under an enforced gate (advisory now).`
         : '✅ No merge-blocking findings (style/correctness advise only).';
-    return `${banner}\n\n${verdictLine}\n\n| severity | kind | file | finding |\n|---|---|---|---|\n${rows}`;
+    return `${banner}\n\n${verdictLine}\n\n| severity | kind | file | finding |\n|---|---|---|---|\n${rows}${esc}`;
 }
 
 function postReview(body: string): void {
@@ -238,7 +303,10 @@ export function main(argv: string[]): 0 | 2 {
             `self-review-gate (dry-run — no spend, advisory):\n` +
                 `  skills: ${plan.skills.join(', ')}\n` +
                 `  files:  ${plan.files.length}\n` +
-                `  ${plan.note}\n`,
+                `  ${plan.note}\n` +
+                (plan.escalation.length
+                    ? `  escalation: ${plan.escalation.join('; ')} → recommend /council:pr (run-time authorized)\n`
+                    : `  escalation: none (diff is small and not claim-affecting)\n`),
         );
         return 0;
     }
@@ -282,7 +350,7 @@ export function main(argv: string[]): 0 | 2 {
             return 0; // no credit / transport / API error → never blocks the merge
         }
         const findings = parseFindings(resp.text);
-        const body = renderReview(findings, enforce);
+        const body = renderReview(findings, enforce, plan.escalation);
         postReview(body);
 
         const code = gateVerdict(findings, { enforce });

package/src/scripts/validate_flow_teams.ts

@@ -0,0 +1,127 @@
+#!/usr/bin/env tsx
+/**
+ * Validate the optional `team:` annotation on flows (`src/flows/*.yaml`).
+ *
+ * A demand-probe primitive (road-to-persona-library-harvest.md Phase 3): a flow
+ * MAY declare `team: { personas: [...], skills: [...] }` naming the persona/skill
+ * team its work typically pulls in. This validator checks referential
+ * integrity — every persona id resolves to `src/agent-src/personas/<id>.md`,
+ * every skill slug to a real `skills/<slug>/SKILL.md` — so a typo is caught, but
+ * it adds NO execution semantics (subagent-orchestration stays the executor) and
+ * no new artifact class. If organic use grows (≥ 5 flows carrying `team:` with a
+ * repeated conditional shape), THAT is the signal to design a roster schema —
+ * not before.
+ *
+ * Exit 0 clean (incl. no flow carrying `team:`) · 1 on an unresolved reference
+ * · 2 usage.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import YAML from 'yaml';
+
+import { resolve_logical } from './_lib/agent_src.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const FLOWS_DIR = path.join(ROOT, 'src', 'flows');
+const PERSONAS_DIR = path.join(ROOT, 'src', 'agent-src', 'personas');
+const NON_FLOW = new Set(['surface-map.yaml', 'cookbook.yaml']);
+
+function _isFile(p: string): boolean {
+    try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+function _rel(p: string): string {
+    return path.relative(ROOT, p).split(path.sep).join('/');
+}
+function _personaExists(id: string): boolean {
+    return _isFile(path.join(PERSONAS_DIR, `${id}.md`));
+}
+function _skillExists(slug: string): boolean {
+    return resolve_logical(`skills/${slug}/SKILL.md`) !== null;
+}
+
+interface Violation { file: string; reason: string; }
+
+export function checkFile(abs: string): Violation[] {
+    const rel = _rel(abs);
+    let data: unknown;
+    try {
+        data = YAML.parse(fs.readFileSync(abs, 'utf-8'), { version: '1.1' });
+    } catch (e) {
+        return [{ file: rel, reason: `not valid YAML: ${e instanceof Error ? e.message : String(e)}` }];
+    }
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) return [];
+    const team = (data as Record<string, unknown>)['team'];
+    if (team === undefined || team === null) return [];
+    if (typeof team !== 'object' || Array.isArray(team)) {
+        return [{ file: rel, reason: '`team` must be a mapping with optional `personas` / `skills` arrays' }];
+    }
+    const vios: Violation[] = [];
+    const personas = (team as Record<string, unknown>)['personas'];
+    for (const id of Array.isArray(personas) ? personas : []) {
+        if (typeof id === 'string' && !_personaExists(id)) {
+            vios.push({ file: rel, reason: `team.personas: persona '${id}' does not resolve (no src/agent-src/personas/${id}.md)` });
+        }
+    }
+    const skills = (team as Record<string, unknown>)['skills'];
+    for (const slug of Array.isArray(skills) ? skills : []) {
+        if (typeof slug === 'string' && !_skillExists(slug)) {
+            vios.push({ file: rel, reason: `team.skills: skill '${slug}' does not resolve (no skills/${slug}/SKILL.md)` });
+        }
+    }
+    return vios;
+}
+
+export function main(argv?: string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    if (args.includes('-h') || args.includes('--help')) {
+        process.stdout.write('usage: validate_flow_teams [--quiet]\n');
+        return 0;
+    }
+    const unknown = args.filter((a) => a !== '--quiet');
+    if (unknown.length > 0) {
+        process.stderr.write(`unrecognized argument: ${unknown[0]}\nusage: validate_flow_teams [--quiet]\n`);
+        return 2;
+    }
+    const quiet = args.includes('--quiet');
+
+    let files: string[];
+    try {
+        files = fs.readdirSync(FLOWS_DIR).filter((n) => n.endsWith('.yaml') && !NON_FLOW.has(n)).sort();
+    } catch {
+        process.stderr.write(`flows dir not found: ${FLOWS_DIR}\n`);
+        return 0; // nothing to validate
+    }
+
+    const vios: Violation[] = [];
+    let annotated = 0;
+    for (const name of files) {
+        const abs = path.join(FLOWS_DIR, name);
+        vios.push(...checkFile(abs));
+        if (/^team:/m.test(fs.readFileSync(abs, 'utf-8'))) annotated++;
+    }
+
+    if (vios.length > 0) {
+        process.stderr.write(`validate_flow_teams: ${vios.length} unresolved reference(s):\n`);
+        for (const v of vios) process.stderr.write(`  ${v.file}: ${v.reason}\n`);
+        return 1;
+    }
+    if (!quiet) {
+        process.stdout.write(`validate_flow_teams: OK — ${annotated} flow(s) carry a \`team:\` annotation, all references resolve.\n`);
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch { return false; }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}