@event4u/agent-config 5.1.0 → 5.3.0

package/scripts/migrate_frontmatter_defaults.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""Migrate artefact frontmatter to omit fields equal to their schema default.
+
+Phase 2 of `road-to-abstraction-reduction.md`. For every skill / rule /
+command / persona, drop any frontmatter field whose value equals the
+`default` declared in its `scripts/schemas/*.json` (preflight Decision C:
+value-equals-default, type-safe). Fields without a schema default
+(`skill.execution.type`, `command.type`, `rule.validator_ignore`) are never
+touched.
+
+The loader injects the same defaults at read time
+(`validate_frontmatter.apply_schema_defaults`), so consumers see the field
+present regardless. Idempotent: a second run is a no-op.
+
+CLI:
+  python3 scripts/migrate_frontmatter_defaults.py [--dry-run] [--deltas PATH]
+
+Exit codes: 0 always (reports counts); non-zero only on I/O error.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from validate_frontmatter import load_schema, parse_frontmatter  # noqa: E402
+from _lib.agent_src import artefact_roots  # noqa: E402
+
+ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_DELTAS = ROOT / "agents" / "evidence" / "analysis" / "abstraction-reduction-deltas.md"
+
+# (subdir, glob, schema name)
+_CATEGORIES = [
+    ("skills", "SKILL.md", "skill"),
+    ("rules", "*.md", "rule"),
+    ("commands", "*.md", "command"),
+    ("personas", "*.md", "persona"),
+]
+
+_FM_RE_OPEN = "---\n"
+
+
+def _same(value: Any, default: Any) -> bool:
+    """Type-safe equality. `True == 1` and `1.0 == 1` must NOT match across
+    types (preflight Decision C). bool is checked first because in Python
+    `isinstance(True, int)` is True."""
+    if isinstance(default, bool):
+        return isinstance(value, bool) and value == default
+    if isinstance(value, bool):
+        return False
+    return type(value) is type(default) and value == default
+
+
+def _plan_drops(fm: dict[str, Any], schema: dict[str, Any]) -> tuple[set[str], set[str], dict[str, set[str]]]:
+    """Return (top_level_drops, full_block_drops, partial_block_drops).
+
+    - top_level_drops: scalar keys whose value == default → drop the line.
+    - full_block_drops: object keys where every *present* sub-key is droppable
+      → drop the whole block.
+    - partial_block_drops: object key → set of droppable sub-keys (block kept).
+    """
+    top: set[str] = set()
+    full: set[str] = set()
+    partial: dict[str, set[str]] = {}
+    props = schema.get("properties", {})
+    for key, prop in props.items():
+        if not isinstance(prop, dict):
+            continue
+        if "default" in prop:
+            if key in fm and _same(fm[key], prop["default"]):
+                top.add(key)
+        elif prop.get("type") == "object" and isinstance(fm.get(key), dict):
+            sub_props = prop.get("properties", {})
+            droppable = {
+                sk for sk, sp in sub_props.items()
+                if isinstance(sp, dict) and "default" in sp
+                and sk in fm[key] and _same(fm[key][sk], sp["default"])
+            }
+            if not droppable:
+                continue
+            present = set(fm[key].keys())
+            if present <= droppable:
+                full.add(key)
+            else:
+                partial[key] = droppable
+    return top, full, partial
+
+
+def _indent(line: str) -> int:
+    return len(line) - len(line.lstrip(" "))
+
+
+def _rewrite_fm_body(body: str, top: set[str], full: set[str], partial: dict[str, set[str]]) -> str:
+    """Remove the planned lines from a frontmatter body, preserving everything
+    else byte-for-byte."""
+    lines = body.split("\n")
+    out: list[str] = []
+    skipping_block = False
+    current_block: str | None = None
+    for line in lines:
+        stripped = line.strip()
+        ind = _indent(line)
+        if skipping_block:
+            # Consume the block's indented children (and blank lines) until a
+            # top-level (indent-0, non-blank) line appears.
+            if stripped == "" or ind > 0:
+                continue
+            skipping_block = False
+            current_block = None
+        if ind == 0 and stripped and not stripped.startswith("#"):
+            key = stripped.split(":", 1)[0].strip()
+            if key in top:
+                continue
+            if key in full:
+                skipping_block = True
+                continue
+            current_block = key if key in partial else None
+            out.append(line)
+            continue
+        # Indented line belonging to current_block.
+        if current_block is not None and ind > 0 and ":" in stripped:
+            sub_key = stripped.split(":", 1)[0].strip()
+            if sub_key in partial.get(current_block, set()):
+                continue
+        out.append(line)
+    return "\n".join(out)
+
+
+def _migrate_file(path: Path, schema: dict[str, Any]) -> int:
+    text = path.read_text(encoding="utf-8")
+    fm, _ = parse_frontmatter(text)
+    if not isinstance(fm, dict):
+        return 0
+    top, full, partial = _plan_drops(fm, schema)
+    if not (top or full or partial):
+        return 0
+    # Locate the frontmatter body span (after the opening `---\n`).
+    if not text.startswith(_FM_RE_OPEN):
+        return 0
+    end = text.find("\n---\n", len(_FM_RE_OPEN))
+    if end == -1:
+        return 0
+    body = text[len(_FM_RE_OPEN):end]
+    new_body = _rewrite_fm_body(body, top, full, partial)
+    if new_body == body:
+        return 0
+    new_text = _FM_RE_OPEN + new_body + text[end:]
+    removed = body.count("\n") - new_body.count("\n")
+    path.write_text(new_text, encoding="utf-8")
+    return removed
+
+
+def _iter(category_subdir: str, glob: str):
+    """Mirror `validate_frontmatter._iter_artefacts` exactly: skills / rules /
+    commands recurse; personas are **non-recursive** (`glob`, not `rglob`) so
+    advisor personas (`personas/advisors/*.md`, a different schema) and the
+    `_template-specialist/` scaffold are never migrated."""
+    for root in artefact_roots():
+        base = root / category_subdir
+        if not base.exists():
+            continue
+        paths = base.glob(glob) if category_subdir == "personas" else base.rglob(glob)
+        for p in sorted(paths):
+            if p.is_file() and not p.is_symlink():
+                if category_subdir == "personas" and p.name.lower() == "readme.md":
+                    continue
+                yield p
+
+
+def run(apply: bool, deltas_path: Path) -> int:
+    per_class_lines: dict[str, int] = defaultdict(int)
+    per_class_files: dict[str, int] = defaultdict(int)
+    for subdir, glob, schema_name in _CATEGORIES:
+        schema = load_schema(schema_name)
+        for path in _iter(subdir, glob):
+            if apply:
+                removed = _migrate_file(path, schema)
+            else:
+                # Dry-run: compute the delta without writing.
+                text = path.read_text(encoding="utf-8")
+                fm, _ = parse_frontmatter(text)
+                if not isinstance(fm, dict) or not text.startswith(_FM_RE_OPEN):
+                    continue
+                end = text.find("\n---\n", len(_FM_RE_OPEN))
+                if end == -1:
+                    continue
+                body = text[len(_FM_RE_OPEN):end]
+                top, full, partial = _plan_drops(fm, schema)
+                new_body = _rewrite_fm_body(body, top, full, partial)
+                removed = body.count("\n") - new_body.count("\n")
+            if removed:
+                per_class_lines[schema_name] += removed
+                per_class_files[schema_name] += 1
+
+    total_lines = sum(per_class_lines.values())
+    total_files = sum(per_class_files.values())
+    verb = "would remove" if not apply else "removed"
+    print(f"frontmatter-default migration ({'dry-run' if not apply else 'apply'}):")
+    for schema_name, _glob, _sn in [(c[2], c[1], c[2]) for c in _CATEGORIES]:
+        if per_class_files.get(schema_name):
+            print(f"  {schema_name:8s}: {verb} {per_class_lines[schema_name]:5d} lines "
+                  f"across {per_class_files[schema_name]} files")
+    print(f"  {'TOTAL':8s}: {verb} {total_lines} lines across {total_files} files")
+
+    if not apply:
+        _write_deltas(deltas_path, per_class_lines, per_class_files, total_lines, total_files)
+        print(f"  delta report → {deltas_path.relative_to(ROOT)}")
+    return 0
+
+
+def _write_deltas(path: Path, lines: dict[str, int], files: dict[str, int],
+                  total_lines: int, total_files: int) -> None:
+    rows = "\n".join(
+        f"| {sn} | {files.get(sn, 0)} | {lines.get(sn, 0)} |"
+        for _sd, _g, sn in _CATEGORIES if files.get(sn)
+    )
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        "# Abstraction-reduction — frontmatter line-count delta\n\n"
+        "> Dry-run prediction from `scripts/migrate_frontmatter_defaults.py "
+        "--dry-run` (road-to-abstraction-reduction.md Phase 2 § Step 2). Lines\n"
+        "> are frontmatter lines dropped because their value equalled the\n"
+        "> schema default; the loader re-injects them at read time.\n\n"
+        "| Class | Files touched | Lines removed |\n"
+        "|---|---:|---:|\n"
+        f"{rows}\n"
+        f"| **TOTAL** | **{total_files}** | **{total_lines}** |\n",
+        encoding="utf-8",
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--dry-run", action="store_true", help="report the delta; write nothing.")
+    parser.add_argument("--deltas", type=Path, default=DEFAULT_DELTAS,
+                        help="dry-run delta report output path.")
+    args = parser.parse_args(argv)
+    return run(apply=not args.dry_run, deltas_path=args.deltas)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/schemas/command.schema.json

@@ -25,6 +25,7 @@
     "disable-model-invocation": {
       "type": "boolean",
       "enum": [true],
+      "default": true,
       "description": "Commands are always user-invoked; model-invocation is disabled."
     },
     "skills": {
@@ -135,6 +136,7 @@
     "lifecycle": {
       "type": "string",
       "enum": ["active", "deprecated", "experimental", "archived"],
+      "default": "active",
       "description": "ADR-013 lifecycle state."
     },
     "trust": {
@@ -142,9 +144,9 @@
       "additionalProperties": false,
       "required": ["level", "confidence", "human_review_required"],
       "properties": {
-        "level": {"type": "string", "enum": ["core", "professional", "experimental", "advisory", "restricted"]},
-        "confidence": {"type": "string", "enum": ["high", "medium", "low"]},
-        "human_review_required": {"type": "boolean"}
+        "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."
     },
@@ -153,8 +155,8 @@
       "additionalProperties": false,
       "required": ["default", "removable"],
       "properties": {
-        "default": {"type": "boolean"},
-        "removable": {"type": "boolean"}
+        "default": {"type": "boolean", "default": true},
+        "removable": {"type": "boolean", "default": false}
       },
       "description": "ADR-013 install hints (default-on at consumer install; user-removable)."
     },

package/scripts/schemas/persona.schema.json

@@ -37,11 +37,13 @@
     },
     "version": {
       "type": "string",
-      "pattern": "^[0-9]+(\\.[0-9]+){0,2}$"
+      "pattern": "^[0-9]+(\\.[0-9]+){0,2}$",
+      "default": "1.0"
     },
     "source": {
       "type": "string",
-      "enum": ["package", "project"]
+      "enum": ["package", "project"],
+      "default": "package"
     }
   }
 }

package/scripts/schemas/rule.schema.json

@@ -14,7 +14,8 @@
     },
     "source": {
       "type": "string",
-      "enum": ["package", "project"]
+      "enum": ["package", "project"],
+      "default": "package"
     },
     "description": {
       "type": "string",
@@ -116,6 +117,7 @@
     "lifecycle": {
       "type": "string",
       "enum": ["active", "deprecated", "experimental", "archived"],
+      "default": "active",
       "description": "ADR-013 lifecycle state."
     },
     "trust": {
@@ -123,9 +125,9 @@
       "additionalProperties": false,
       "required": ["level", "confidence", "human_review_required"],
       "properties": {
-        "level": {"type": "string", "enum": ["core", "professional", "experimental", "advisory", "restricted"]},
-        "confidence": {"type": "string", "enum": ["high", "medium", "low"]},
-        "human_review_required": {"type": "boolean"}
+        "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."
     },
@@ -134,8 +136,8 @@
       "additionalProperties": false,
       "required": ["default", "removable"],
       "properties": {
-        "default": {"type": "boolean"},
-        "removable": {"type": "boolean"}
+        "default": {"type": "boolean", "default": true},
+        "removable": {"type": "boolean", "default": false}
       },
       "description": "ADR-013 install hints (default-on at consumer install; user-removable)."
     }

package/scripts/schemas/skill.schema.json

@@ -20,7 +20,8 @@
     },
     "source": {
       "type": "string",
-      "enum": ["package", "project"]
+      "enum": ["package", "project"],
+      "default": "package"
     },
     "domain": {
       "type": "string",
@@ -140,6 +141,7 @@
     "lifecycle": {
       "type": "string",
       "enum": ["active", "deprecated", "experimental", "archived"],
+      "default": "active",
       "description": "ADR-013 lifecycle state."
     },
     "trust": {
@@ -147,9 +149,9 @@
       "additionalProperties": false,
       "required": ["level", "confidence", "human_review_required"],
       "properties": {
-        "level": {"type": "string", "enum": ["core", "professional", "experimental", "advisory", "restricted"]},
-        "confidence": {"type": "string", "enum": ["high", "medium", "low"]},
-        "human_review_required": {"type": "boolean"}
+        "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."
     },
@@ -158,8 +160,8 @@
       "additionalProperties": false,
       "required": ["default", "removable"],
       "properties": {
-        "default": {"type": "boolean"},
-        "removable": {"type": "boolean"}
+        "default": {"type": "boolean", "default": true},
+        "removable": {"type": "boolean", "default": false}
       },
       "description": "ADR-013 install hints (default-on at consumer install; user-removable)."
     }

package/scripts/skill_linter.py

@@ -33,6 +33,7 @@ from typing import Iterable, List, Literal, Optional
 # Sibling module — stdlib-only frontmatter schema validator.
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from validate_frontmatter import (  # noqa: E402
+    apply_schema_defaults,
     parse_frontmatter as parse_frontmatter_for_schema,
     load_schema,
     validate as validate_against_schema,
@@ -1511,11 +1512,10 @@ def lint_rule(path: Path, text: str) -> LintResult:
         elif rule_type not in VALID_RULE_TYPES:
             issues.append(Issue("error", "invalid_type", f"Invalid type '{rule_type}'; must be 'always', 'auto', or 'manual'"))
 
-        # source field
+        # source field — optional (schema default `package` injected at read);
+        # validate the value only when present.
         rule_source = extract_frontmatter_field(frontmatter, SOURCE_PATTERN)
-        if rule_source is None:
-            issues.append(Issue("error", "missing_source", "Frontmatter missing 'source' field (must be 'package' or 'project')"))
-        elif rule_source not in VALID_RULE_SOURCES:
+        if rule_source is not None and rule_source not in VALID_RULE_SOURCES:
             issues.append(Issue("error", "invalid_source", f"Invalid source '{rule_source}'; must be 'package' or 'project'"))
 
         # description required for auto rules
@@ -1689,12 +1689,10 @@ def lint_command(path: Path, text: str) -> LintResult:
         if not name_match or not name_match.group(1).strip():
             issues.append(Issue("error", "missing_name", "Frontmatter missing 'name' field"))
 
-        # disable-model-invocation field
+        # disable-model-invocation field — optional (schema default `true`
+        # injected at read); validate the value only when present.
         dmi_match = DISABLE_MODEL_PATTERN.search(frontmatter)
-        if not dmi_match:
-            issues.append(Issue("error", "missing_disable_model_invocation",
-                                "Frontmatter missing 'disable-model-invocation: true' (required for Claude Code)"))
-        elif dmi_match.group(1) != "true":
+        if dmi_match and dmi_match.group(1) != "true":
             issues.append(Issue("warning", "disable_model_invocation_false",
                                 "disable-model-invocation should be 'true' for commands"))
 
@@ -1839,6 +1837,11 @@ def lint_persona(path: Path, text: str) -> LintResult:
         "role": re.compile(r'^role:\s*"?(.+?)"?\s*$', re.MULTILINE),
         "description": re.compile(r'^description:\s*"?(.+?)"?\s*$', re.MULTILINE),
         "tier": re.compile(r'^tier:\s*"?(\w+)"?\s*$', re.MULTILINE),
+    }
+    # `version` (default "1.0") and `source` (default "package") carry schema
+    # defaults — they are injected at read time, so omitting them is valid.
+    # Validate the value only when present; never require presence.
+    optional_defaulted = {
         "version": re.compile(r'^version:\s*"?(.+?)"?\s*$', re.MULTILINE),
         "source": re.compile(r'^source:\s*"?(package|project)"?\s*$', re.MULTILINE),
     }
@@ -1849,6 +1852,10 @@ def lint_persona(path: Path, text: str) -> LintResult:
             issues.append(Issue("error", f"missing_{field}", f"Persona frontmatter must declare `{field}`"))
         else:
             parsed[field] = value
+    for field, pattern in optional_defaulted.items():
+        value = extract_frontmatter_field(frontmatter, pattern)
+        if value:
+            parsed[field] = value
 
     # id matches filename stem
     if "id" in parsed and parsed["id"] != path.stem:
@@ -3091,6 +3098,11 @@ def lint_frontmatter_schema(path: Path, text: str, artifact_type: str) -> List[I
         # rules/commands/personas; avoid double-reporting here.
         return []
 
+    # Inject schema defaults before validating so artefacts that omit a field
+    # equal to its default (post abstraction-reduction migration) still satisfy
+    # `required` — mirrors validate_frontmatter's own loader path.
+    apply_schema_defaults(data, schema)
+
     issues: List[Issue] = []
     for error in validate_against_schema(data, schema):
         code = f"schema_{error.rule}"

package/scripts/smoke/skills.sh

@@ -25,7 +25,7 @@ log() { [ "$quiet" = "1" ] || printf '%s\n' "$*"; }
 result=$(python3 <<'PY'
 import os, sys, time, hashlib, pathlib, glob
 sys.path.insert(0, "scripts")
-from validate_frontmatter import parse_frontmatter, load_schema, validate
+from validate_frontmatter import parse_frontmatter, load_schema, validate, apply_schema_defaults
 from _lib.agent_src import artefact_roots
 
 # ADR-017: walk every source root, collect skill dirs by logical name.
@@ -60,6 +60,9 @@ for name in sample:
     if fm is None:
         failures.append(f"{name}: no frontmatter")
         continue
+    # Inject schema defaults before validating: artefacts may omit a field
+    # equal to its default (abstraction-reduction), injected at read time.
+    apply_schema_defaults(fm, schema)
     errs = validate(fm, schema)
     if errs:
         for e in errs:

package/scripts/validate_frontmatter.py

@@ -33,6 +33,7 @@ __all__ = [
     "validate",
     "load_schema",
     "parse_frontmatter",
+    "apply_schema_defaults",
 ]
 
 _FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
@@ -234,6 +235,75 @@ def load_schema(artefact_type: str) -> dict[str, Any]:
     return data
 
 
+# --- Schema-default injection ----------------------------------------------
+
+def _object_defaults(schema: dict[str, Any]) -> dict[str, Any]:
+    """Build the default value for an absent object property from the
+    ``default`` keywords declared on its sub-properties. Returns ``{}`` when
+    no sub-property declares a default (so the object is never fabricated).
+    """
+    out: dict[str, Any] = {}
+    for sub_key, sub_schema in (schema.get("properties") or {}).items():
+        if not isinstance(sub_schema, dict):
+            continue
+        if "default" in sub_schema:
+            out[sub_key] = sub_schema["default"]
+        elif sub_schema.get("type") == "object":
+            nested = _object_defaults(sub_schema)
+            if nested:
+                out[sub_key] = nested
+    return out
+
+
+def apply_schema_defaults(data: dict[str, Any], schema: dict[str, Any]) -> dict[str, Any]:
+    """Inject schema ``default`` values into ``data`` for absent keys, in place.
+
+    Mirrors the contract in
+    ``agents/evidence/analysis/abstraction-reduction-preflight.md``: a field
+    omitted on disk reads back as its schema default, so downstream consumers
+    that require the field present keep working unchanged after the
+    frontmatter-default migration (road-to-abstraction-reduction.md).
+
+    Behaviour:
+    - A scalar property with a ``default`` is injected when absent.
+    - An object property whose sub-properties declare defaults is, when absent,
+      reconstructed from those sub-defaults; when present (a dict), its absent
+      sub-keys are filled. Objects with no sub-defaults (e.g. ``execution``) are
+      never fabricated.
+    - Present values are never overwritten — injection only fills gaps.
+
+    Returns the same ``data`` dict for convenience. Non-dict input is returned
+    untouched.
+    """
+    if not isinstance(data, dict):
+        return data
+    for key, prop in (schema.get("properties") or {}).items():
+        if not isinstance(prop, dict):
+            continue
+        if "default" in prop:
+            data.setdefault(key, prop["default"])
+            continue
+        if prop.get("type") == "object":
+            if key in data and isinstance(data[key], dict):
+                _fill_object_defaults(data[key], prop)
+            elif key not in data:
+                reconstructed = _object_defaults(prop)
+                if reconstructed:
+                    data[key] = reconstructed
+    return data
+
+
+def _fill_object_defaults(obj: dict[str, Any], schema: dict[str, Any]) -> None:
+    """Fill absent sub-keys of a present object from sub-property defaults."""
+    for sub_key, sub_schema in (schema.get("properties") or {}).items():
+        if not isinstance(sub_schema, dict):
+            continue
+        if "default" in sub_schema:
+            obj.setdefault(sub_key, sub_schema["default"])
+        elif sub_schema.get("type") == "object" and isinstance(obj.get(sub_key), dict):
+            _fill_object_defaults(obj[sub_key], sub_schema)
+
+
 # --- Validator core (Draft-07 subset) --------------------------------------
 
 _JSON_TYPES: dict[str, tuple[type, ...]] = {
@@ -476,6 +546,10 @@ def _main() -> int:
                 # Other tooling flags missing frontmatter; don't double-report.
                 continue
             schema = load_schema(artefact_type)
+            # Inject schema defaults before validation so artefacts that omit a
+            # field equal to its default still satisfy `required`
+            # (road-to-abstraction-reduction.md Phase 1).
+            apply_schema_defaults(data, schema)
             errors = validate(data, schema)
             fatal = [e for e in errors if e.severity == "error"]
             warnings = [e for e in errors if e.severity == "warning"]