@event4u/agent-config 1.18.0 → 1.20.0

package/scripts/roadmap_progress_hook.py

@@ -114,6 +114,11 @@ def run(stdin_text: str, *, consumer_root: Path, verbose: bool = False) -> int:
         except json.JSONDecodeError:
             return 0  # malformed stdin → silent no-op, never block
 
+    # Unwrap dispatcher envelope (Phase 7.3, hook-architecture-v1.md).
+    if all(k in payload for k in ("schema_version", "platform", "event", "payload")):
+        inner = payload.get("payload")
+        payload = inner if isinstance(inner, dict) else {}
+
     tool = payload.get("tool_name") or payload.get("toolName") or payload.get("tool")
     if not isinstance(tool, str) or tool not in WRITE_TOOLS:
         return 0

package/scripts/schemas/skill.schema.json

@@ -37,6 +37,11 @@
         "pattern": "^[a-z][a-z0-9-]*$"
       }
     },
+    "tier": {
+      "type": "string",
+      "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.uncompressed/rules/skill-quality.md."
+    },
     "execution": {
       "type": "object",
       "additionalProperties": false,

package/scripts/skill_linter.py

@@ -99,6 +99,17 @@ TYPE_PATTERN = re.compile(r'^type:\s*"?(always|auto)"?\s*$', re.MULTILINE)
 SOURCE_PATTERN = re.compile(r'^source:\s*"?(package|project)"?\s*$', re.MULTILINE)
 STATUS_PATTERN = re.compile(r'^status:\s*"?(active|deprecated|superseded)"?\s*$', re.MULTILINE)
 REPLACED_BY_PATTERN = re.compile(r'^replaced_by:\s*"?([\w-]+)"?\s*$', re.MULTILINE)
+TIER_PATTERN = re.compile(r'^tier:\s*"?([\w-]+)"?\s*$', re.MULTILINE)
+
+# --- Senior-tier required-block patterns (skill-quality.md § Senior-Tier Required Structure) ---
+# Heading-only checks; detail-shape lives in skill-quality-mechanics.md.
+SENIOR_RELATED_SKILLS_PATTERN = re.compile(r"^##\s+Related Skills\s*$", re.MULTILINE)
+SENIOR_RELATED_WHEN_PATTERN = re.compile(r"\*\*WHEN to use this\*\*", re.IGNORECASE)
+SENIOR_RELATED_WHEN_NOT_PATTERN = re.compile(r"\*\*WHEN NOT to use this\*\*", re.IGNORECASE)
+SENIOR_PROACTIVE_PATTERN = re.compile(
+    r"^##\s+When the agent should load this\s*$", re.MULTILINE
+)
+SENIOR_OUTPUT_PATTERN = re.compile(r"^##\s+Output\s*$", re.MULTILINE)
 H1_PATTERN = re.compile(r"^# .+", re.MULTILINE)
 DOUBLE_BLANK_PATTERN = re.compile(r"\n{3,}")
 
@@ -415,6 +426,11 @@ def lint_skill(path: Path, text: str) -> LintResult:
         if execution is not None:
             issues.extend(lint_execution_metadata(execution))
 
+        # --- Senior-tier required-block check (skill-quality.md § Senior-Tier Required Structure) ---
+        tier_match = TIER_PATTERN.search(frontmatter)
+        if tier_match and tier_match.group(1) == "senior":
+            issues.extend(lint_senior_tier_blocks(text))
+
     procedure_block = find_procedure_block(text)
     if procedure_block is not None:
         if not procedure_block:
@@ -603,6 +619,57 @@ def parse_execution_block(frontmatter: str) -> Optional[dict]:
     return result
 
 
+def lint_senior_tier_blocks(text: str) -> List[Issue]:
+    """Validate the four required blocks for `tier: senior` skills.
+
+    Per .agent-src.uncompressed/rules/skill-quality.md § Senior-Tier
+    Required Structure: Context-First lead (description), Related Skills
+    (with WHEN / WHEN NOT lists), Proactive Triggers, Output Artifacts.
+
+    The Context-First lead is checked structurally via description length
+    + content; here we enforce the three section blocks and the WHEN /
+    WHEN NOT two-list pattern inside Related Skills.
+    """
+    issues: List[Issue] = []
+
+    if not SENIOR_RELATED_SKILLS_PATTERN.search(text):
+        issues.append(Issue(
+            "error",
+            "missing_senior_related_skills",
+            "Senior-tier skill missing `## Related Skills` block (skill-quality.md § Senior-Tier Required Structure)",
+        ))
+    else:
+        related_block = extract_section_block(text, "Related Skills") or ""
+        if not SENIOR_RELATED_WHEN_PATTERN.search(related_block):
+            issues.append(Issue(
+                "error",
+                "missing_senior_related_when",
+                "Senior-tier `## Related Skills` block missing `**WHEN to use this**` list",
+            ))
+        if not SENIOR_RELATED_WHEN_NOT_PATTERN.search(related_block):
+            issues.append(Issue(
+                "error",
+                "missing_senior_related_when_not",
+                "Senior-tier `## Related Skills` block missing `**WHEN NOT to use this**` list",
+            ))
+
+    if not SENIOR_PROACTIVE_PATTERN.search(text):
+        issues.append(Issue(
+            "error",
+            "missing_senior_proactive_triggers",
+            "Senior-tier skill missing `## When the agent should load this` block",
+        ))
+
+    if not SENIOR_OUTPUT_PATTERN.search(text):
+        issues.append(Issue(
+            "error",
+            "missing_senior_output_artifacts",
+            "Senior-tier skill missing `## Output` block declaring artifact name + shape",
+        ))
+
+    return issues
+
+
 def lint_execution_metadata(execution: dict) -> List[Issue]:
     """Validate the execution block of a skill."""
     issues: List[Issue] = []
@@ -1656,6 +1723,70 @@ def lint_governance(path: Path, text: str, artifact_type: str, repo_root: Path |
     return issues
 
 
+# --- Structural malice check (see road-to-suite-closure Phase 5) ---
+#
+# Five regex patterns scan skill / rule / command bodies for **structural**
+# (not semantic) malice. Findings surface as ``Issue("error",
+# "malice:<pattern>", "<line>:<matched>")`` so ``compute_exit_code`` can
+# emit exit code 3 (security-failure), distinct from 2 (build-failure).
+# Semantic checks (PII leakage, prompt injection) are deferred to v2.
+
+# (a) credential exfil — curl|wget piping ${TOKEN}/${KEY}/${SECRET}/...
+#     env vars or hitting ~/.aws/ ~/.ssh/ secrets.
+_MALICE_CRED_EXFIL = re.compile(
+    r"\b(?:curl|wget)\b[^\n]*"
+    r"(?:\$\{?[A-Z_]*(?:TOKEN|KEY|SECRET|PASSWORD|CREDENTIAL|API)[A-Z_]*\}?"
+    r"|~/\.(?:aws|ssh)/)"
+)
+# (b) arbitrary execution — eval/exec over a network-fetched payload, or
+#     `bash <(curl ...)` / `sh <(wget ...)` style remote-execution.
+_MALICE_REMOTE_EXEC = re.compile(
+    r"(?:\b(?:eval|exec)\s*\([^)]*(?:curl|wget|requests\.get|urllib)"
+    r"|\b(?:bash|sh|zsh)\s*<\s*\(\s*(?:curl|wget))"
+)
+# (c) force-push to a protected ref.
+_MALICE_FORCE_PUSH = re.compile(
+    r"\bgit\s+push\b[^\n]*--force(?:-with-lease)?\b[^\n]*"
+    r"\b(?:main|master|prod|production|release)\b"
+)
+# (d) world-readable secrets — chmod 0?[4567]xx on .pem/.key/.env files.
+_MALICE_CHMOD_SECRETS = re.compile(
+    r"\bchmod\s+0?[4567]\d{2}\s+[^\n]*\.(?:pem|key|env)\b"
+)
+# (e) unbounded subprocess shell injection — shell=True interpolating ${VAR}.
+_MALICE_SHELL_INJECT = re.compile(
+    r"\bsubprocess\.[A-Za-z_]+\s*\([^)]*shell\s*=\s*True[^)]*\$\{"
+)
+
+_MALICE_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    ("cred_exfil", _MALICE_CRED_EXFIL),
+    ("remote_exec", _MALICE_REMOTE_EXEC),
+    ("force_push_protected", _MALICE_FORCE_PUSH),
+    ("chmod_secrets", _MALICE_CHMOD_SECRETS),
+    ("shell_injection", _MALICE_SHELL_INJECT),
+]
+
+
+def check_structural_malice(text: str) -> List[Issue]:
+    """Return one Issue per malice match. Empty list when clean.
+
+    Issue shape: ``Issue("error", f"malice:{name}", f"{line}:{matched}")``.
+    The ``format_text`` renderer special-cases the ``malice:`` code prefix
+    to emit ``<path>:<line>:malice:<pattern>:<matched>`` per Phase 5.2.
+    """
+    issues: List[Issue] = []
+    for lineno, raw in enumerate(text.splitlines(), start=1):
+        for name, pattern in _MALICE_PATTERNS:
+            match = pattern.search(raw)
+            if match:
+                issues.append(Issue(
+                    severity="error",
+                    code=f"malice:{name}",
+                    message=f"{lineno}:{match.group(0).strip()}",
+                ))
+    return issues
+
+
 # --- Output-schema check (see road-to-trigger-evals Phase 3.5) ---
 #
 # Skills that freeze an output shape (`refine-ticket`, `estimate-ticket`)
@@ -1865,11 +1996,36 @@ def lint_file(path: Path, repo_root: Path | None = None) -> LintResult:
             result.issues.extend(schema_issues)
             result.status = classify_status(result.issues)
 
+    # Post-processing: structural malice scan (errors). Skills, rules,
+    # and commands carry executable patterns; guidelines/personas are
+    # prose-only and skipped to keep noise low.
+    if artifact_type in ("skill", "rule", "command"):
+        malice_issues = check_structural_malice(text)
+        if malice_issues:
+            result.issues.extend(malice_issues)
+            result.status = classify_status(result.issues)
+
     return result
 
 
 def format_text(results: list[LintResult]) -> str:
     lines: list[str] = []
+    # Phase 5.2: malice findings render in the spec shape
+    # ``<path>:<line>:malice:<pattern>:<matched>`` ahead of the badge
+    # block so security-failures are grep-able from the top.
+    malice_total = 0
+    for result in results:
+        for issue in result.issues:
+            if issue.code.startswith("malice:"):
+                pattern_name = issue.code.split(":", 1)[1]
+                lineno, _, matched = issue.message.partition(":")
+                lines.append(
+                    f"{result.file}:{lineno}:malice:{pattern_name}:{matched}"
+                )
+                malice_total += 1
+    if malice_total:
+        lines.append("")
+
     for result in results:
         badge = {"pass": "[PASS]", "pass_with_warnings": "[WARN]", "fail": "[FAIL]"}[result.status]
         lines.append(f"{badge} {result.file} ({result.artifact_type})")
@@ -1888,7 +2044,8 @@ def format_text(results: list[LintResult]) -> str:
     fails = sum(1 for r in results if r.status == "fail")
     warns = sum(1 for r in results if r.status == "pass_with_warnings")
     passes = sum(1 for r in results if r.status == "pass")
-    lines.append(f"Summary: {passes} pass, {warns} warn, {fails} fail, {total} total")
+    suffix = f", {malice_total} malice" if malice_total else ""
+    lines.append(f"Summary: {passes} pass, {warns} warn, {fails} fail, {total} total{suffix}")
     return "\n".join(lines)
 
 
@@ -2087,6 +2244,11 @@ def check_duplication(root: Path) -> list[LintResult]:
 
 
 def compute_exit_code(results: list[LintResult], strict_warnings: bool) -> int:
+    # Phase 5.2: structural-malice findings emit exit code 3 (security-
+    # failure), distinct from 2 (build-failure) so CI surfaces can split.
+    for r in results:
+        if any(issue.code.startswith("malice:") for issue in r.issues):
+            return 3
     if any(r.status == "fail" for r in results):
         return 2
     if any(r.status == "pass_with_warnings" for r in results) and strict_warnings:

package/scripts/sync_agent_settings.py

@@ -1,15 +1,20 @@
 #!/usr/bin/env python3
-"""Sync `.agent-settings.yml` against the template + profile.
+"""Sync `.agent-settings.yml` against the template + profile (additive merge).
 
 Applies the section-aware merge rules documented in
 `docs/guidelines/agent-infra/layered-settings.md`:
 
-- Template section order always wins — reorder keys to match.
-- Existing user scalar values are preserved verbatim (as parsed).
-- Missing keys land with their template / profile default.
-- Template comments replace user comments in the same position.
-- Unknown user keys (not in the template) are preserved in a trailing
-  `_user:` block so custom additions never get silently dropped.
+- **User lines are preserved verbatim** — comments, quoting, and key order
+  survive every sync. Existing values, custom inline comments, and
+  user-chosen ordering are never modified.
+- Missing template keys are inserted (leaf into existing parent section,
+  full subtree at EOF for entirely missing top-level sections).
+- Top-level user-only sections (no home in the template) are moved to a
+  single-level `_user:` block at the end of the file.
+- The `_user:` block is single-level only — legacy multi-prefix
+  corruption (`_user._user.foo`) heals to `foo` on the next sync.
+- Template comment changes on already-existing user keys do **not**
+  propagate (existing line untouched is the deal).
 
 Idempotent — writing a file that is already in sync is a no-op.
 
@@ -33,7 +38,8 @@ import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
-import install as _install  # noqa: E402 — shares _yaml_scalar + _replace_template_value
+import install as _install  # noqa: E402 — profile parsing + template rendering
+import sync_yaml_rt as _rt  # noqa: E402 — additive round-trip merge
 
 try:
     import yaml  # type: ignore
@@ -46,126 +52,6 @@ DEFAULT_TEMPLATE = Path(__file__).resolve().parent.parent / "config" / "agent-se
 DEFAULT_PROFILE_DIR = Path(__file__).resolve().parent.parent / "config" / "profiles"
 
 
-def _flatten(data: dict, prefix: str = "") -> dict[str, object]:
-    """Flatten nested dicts to dotted keys — recurses to all leaves.
-
-    Lists, scalars, and ``None`` are leaves. Dicts are walked and their
-    keys folded into the dotted path.
-    """
-    out: dict[str, object] = {}
-    for key, value in data.items():
-        path = f"{prefix}{key}"
-        if isinstance(value, dict):
-            out.update(_flatten(value, prefix=f"{path}."))
-        else:
-            out[path] = value
-    return out
-
-
-def _as_yaml_value(value: object) -> str | None:
-    """Format *value* as an inline-YAML literal.
-
-    Returns ``None`` when the value cannot be safely represented as a
-    scalar / flow-style sequence (e.g. unsupported types). Callers
-    must skip those keys so the template default sticks instead of
-    producing malformed YAML.
-    """
-    if isinstance(value, bool):
-        return "true" if value else "false"
-    if isinstance(value, int):
-        return str(value)
-    if isinstance(value, float):
-        return repr(value)
-    if value is None:
-        return "~"
-    if isinstance(value, list):
-        items: list[str] = []
-        for item in value:
-            rendered = _as_yaml_value(item)
-            if rendered is None:
-                return None
-            items.append(rendered)
-        return "[" + ", ".join(items) + "]"
-    if isinstance(value, str):
-        return _install._yaml_scalar(value)
-    return None
-
-
-def _template_keys(template_body: str) -> set[str]:
-    """Return the set of dotted keys declared by the rendered template."""
-    data = yaml.safe_load(template_body) or {}
-    if not isinstance(data, dict):
-        return set()
-    return set(_flatten(data).keys())
-
-
-def _apply_user_values(template_body: str, user_flat: dict[str, object]) -> str:
-    """Overlay every known user value on the rendered template body.
-
-    Keys whose value cannot be rendered inline (see :func:`_as_yaml_value`)
-    are skipped so the template default survives instead of corrupting
-    the file.
-    """
-    body = template_body
-    for dotted, value in user_flat.items():
-        rendered = _as_yaml_value(value)
-        if rendered is None:
-            continue
-        body = _install._replace_template_value_raw(body, dotted, rendered)
-    return body
-
-
-def _append_unknown(body: str, user_flat: dict[str, object], known: set[str]) -> str:
-    """Emit user keys that have no home in the template under `_user:`."""
-    unknown = sorted(k for k in user_flat if k not in known)
-    if not unknown:
-        return body
-    lines = [
-        "",
-        "# Unknown keys preserved by sync_agent_settings.py — review and move",
-        "# them into the template or drop them.",
-        "_user:",
-    ]
-    for key in unknown:
-        rendered = _as_yaml_value(user_flat[key])
-        if rendered is None:
-            continue
-        lines.append(f"  {key}: {rendered}")
-    suffix = "\n".join(lines) + "\n"
-    return body + (suffix if body.endswith("\n") else "\n" + suffix)
-
-
-def render_target(template_body: str, user_data: dict) -> str:
-    """Return the desired `.agent-settings.yml` body for the given user data.
-
-    The trailing ``_user:`` block (emitted by :func:`_append_unknown`) is
-    already in dotted-key form on every read after the first sync. Re-
-    flattening it would prepend another ``_user.`` segment on every run
-    and accumulate forever, so we strip the wrapper and merge its
-    contents straight into the flat dict.
-    """
-    if user_data:
-        user_only = user_data.pop("_user", None) if isinstance(user_data, dict) else None
-        user_flat = _flatten(user_data)
-        if isinstance(user_only, dict):
-            for key, value in user_only.items():
-                # Dotted keys round-trip verbatim — never re-flatten them.
-                if isinstance(key, str):
-                    # Heal legacy corruption: pre-fix syncs prepended a
-                    # `_user.` segment per run, so a key may carry an
-                    # arbitrary number of them. Strip them all back to
-                    # the original leaf path.
-                    healed = key
-                    while healed.startswith("_user."):
-                        healed = healed[len("_user."):]
-                    user_flat[healed] = value
-    else:
-        user_flat = {}
-    known = _template_keys(template_body)
-    body = _apply_user_values(template_body, user_flat)
-    return _append_unknown(body, user_flat, known)
-
-
 def load_profile(profile_dir: Path, profile: str) -> dict[str, str]:
     profile_source = profile_dir / f"{profile}.ini"
     if not profile_source.is_file():
@@ -231,10 +117,27 @@ def main(argv: list[str] | None = None) -> int:
     except FileNotFoundError as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2
+    except yaml.YAMLError as exc:
+        print(f"error: cannot parse {target}: {exc}", file=sys.stderr)
+        return 2
 
-    new_text = render_target(template_body, user_data)
     existing_text = target.read_text(encoding="utf-8") if target.is_file() else ""
 
+    if existing_text:
+        # Additive merge — preserves user lines verbatim, inserts only
+        # the template keys the user is missing.
+        try:
+            new_text = _rt.sync(existing_text, template_body)
+        except ValueError as exc:
+            print(
+                f"error: cannot parse {target}: {exc}",
+                file=sys.stderr,
+            )
+            return 2
+    else:
+        # First-run / file absent — write the rendered template as-is.
+        new_text = template_body
+
     if new_text == existing_text:
         if not args.quiet:
             print(f"✅  {target}: already in sync (profile={profile})")