@event4u/agent-config 1.34.0 → 1.36.0

package/scripts/check_memory.py

@@ -49,6 +49,19 @@ REQUIRED_KEYS = {
 }
 VALID_STATUS = {"active", "deprecated", "archived"}
 VALID_CONFIDENCE = {"low", "medium", "high"}
+# `priority` is optional (default `normal`); enum is the smallest set that
+# solves the tier-0 surfacing use case. See `road-to-dream-skill-adoption.md`
+# § B2 and the Phase 2 council brief for why the `high` tier was rejected.
+VALID_PRIORITY = {"critical", "normal", "low"}
+# Soft-cap on `priority: critical` entries per memory type. Tier-0 inflation
+# is the failure mode: when too many entries claim "always surface", the
+# slice loses signal. Warn (not fail) when the cap is exceeded so curators
+# notice without being blocked.
+CRITICAL_WARN_THRESHOLD = 10
+# Stale-critical guard: a `priority: critical` entry that hasn't been
+# re-validated in this many days emits a warning. Surfaced separately
+# from the generic `stale:` info so reviewers see it before merge.
+CRITICAL_STALE_DAYS = 90
 KNOWN_TYPES = {
     "domain-invariants", "architecture-decisions",
     "incident-learnings", "product-rules",
@@ -69,6 +82,19 @@ REDACTION_PATTERNS = [
     (re.compile(r"\b192\.168\.\d{1,3}\.\d{1,3}\b"), "internal ipv4 range"),
 ]
 
+# Date-discipline — relative-date phrases without an ISO YYYY-MM-DD anchor
+# within ±20 chars are rejected. Memory entries that say "yesterday" or
+# "last week" rot the moment the file is re-read on another day; the
+# anchor pins meaning. See `road-to-dream-skill-adoption.md` § A5.
+RELATIVE_DATE_PATTERN = re.compile(
+    r"(?i)\b(yesterday|today|tomorrow|"
+    r"last\s+(?:week|month|year)|"
+    r"next\s+(?:week|month|year)|"
+    r"this\s+(?:week|month|year))\b"
+)
+ISO_DATE_PATTERN = re.compile(r"\b\d{4}-\d{2}-\d{2}\b")
+DATE_ANCHOR_WINDOW = 20
+
 
 @dataclass
 class Finding:
@@ -105,7 +131,13 @@ def _memory_type(path: Path) -> str:
     return stem[:-len(".example")] if stem.endswith(".example") else stem
 
 
-def _validate_entry(entry: dict, path: Path, seen_ids: set, findings: List[Finding]):
+def _validate_entry(
+    entry: dict,
+    path: Path,
+    seen_ids: set,
+    findings: List[Finding],
+    critical_counts: Optional[dict] = None,
+):
     eid = entry.get("id", "")
     missing = REQUIRED_KEYS - set(entry.keys())
     for key in sorted(missing):
@@ -116,6 +148,14 @@ def _validate_entry(entry: dict, path: Path, seen_ids: set, findings: List[Findi
     if entry.get("confidence") and entry["confidence"] not in VALID_CONFIDENCE:
         findings.append(Finding(str(path), 0, "error",
                                 f"invalid confidence '{entry['confidence']}'", eid))
+    # Priority is optional (defaults to `normal` at read time). When present
+    # it MUST be one of the three-tier enum — see VALID_PRIORITY for the
+    # rationale on rejecting a fourth `high` tier.
+    priority = entry.get("priority")
+    if priority is not None and priority not in VALID_PRIORITY:
+        findings.append(Finding(str(path), 0, "error",
+                                f"invalid priority '{priority}' "
+                                f"(expected one of {sorted(VALID_PRIORITY)})", eid))
     sources = entry.get("source") or []
     if not isinstance(sources, list) or len(sources) < 1:
         findings.append(Finding(str(path), 0, "error",
@@ -131,6 +171,26 @@ def _validate_entry(entry: dict, path: Path, seen_ids: set, findings: List[Findi
         if age > days and entry.get("status") == "active":
             findings.append(Finding(str(path), 0, "info",
                                     f"stale: last_validated {age} days ago (limit {days})", eid))
+    # Critical-stale guard: a `priority: critical` entry that has not been
+    # re-validated within CRITICAL_STALE_DAYS surfaces as a warning, even
+    # when the entry's own `review_after_days` is more lenient. Critical
+    # entries surface on every /memory:load — they have a tighter SLA.
+    if (
+        priority == "critical"
+        and entry.get("status") == "active"
+        and isinstance(lv, _dt.date)
+    ):
+        crit_age = (_dt.date.today() - lv).days
+        if crit_age > CRITICAL_STALE_DAYS:
+            findings.append(Finding(
+                str(path), 0, "warning",
+                f"critical-stale: last_validated {crit_age} days ago "
+                f"(critical SLA is {CRITICAL_STALE_DAYS} days)", eid))
+    # Tier-0 inflation tracking — increment per memory type. The aggregate
+    # warning is emitted in main() after all files are validated.
+    if critical_counts is not None and priority == "critical" and entry.get("status") == "active":
+        mtype = _memory_type(path)
+        critical_counts[mtype] = critical_counts.get(mtype, 0) + 1
 
 
 def _check_redaction(path: Path, findings: List[Finding]):
@@ -144,12 +204,43 @@ def _check_redaction(path: Path, findings: List[Finding]):
                                         f"possible leak: {label}"))
 
 
-def _validate_file(path: Path, findings: List[Finding]):
+def _check_date_discipline(path: Path, findings: List[Finding]):
+    """Reject relative-date phrases without an ISO YYYY-MM-DD anchor.
+
+    A curated memory entry that says "fixed yesterday" rots silently
+    the moment the file is re-read on a different day. We require an
+    ISO date within ±20 chars of every relative phrase so the meaning
+    survives the calendar.
+    """
+    for line_no, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+        # Skip comments and the YAML key for `last_validated` itself.
+        stripped = line.lstrip()
+        if stripped.startswith("#") or stripped.startswith("last_validated"):
+            continue
+        for match in RELATIVE_DATE_PATTERN.finditer(line):
+            start = max(0, match.start() - DATE_ANCHOR_WINDOW)
+            end = min(len(line), match.end() + DATE_ANCHOR_WINDOW)
+            window = line[start:end]
+            if ISO_DATE_PATTERN.search(window):
+                continue
+            phrase = match.group(0)
+            findings.append(Finding(
+                str(path), line_no, "error",
+                f"relative date '{phrase}' without an ISO YYYY-MM-DD anchor "
+                f"within ±{DATE_ANCHOR_WINDOW} chars (re-anchor before commit)"))
+
+
+def _validate_file(
+    path: Path,
+    findings: List[Finding],
+    critical_counts: Optional[dict] = None,
+):
     mtype = _memory_type(path)
     if mtype not in KNOWN_TYPES:
         findings.append(Finding(str(path), 0, "warning",
                                 f"unknown memory type '{mtype}'"))
     _check_redaction(path, findings)
+    _check_date_discipline(path, findings)
     try:
         data = _load_yaml(path) or {}
     except Exception as exc:  # yaml.YAMLError or anything else
@@ -163,7 +254,7 @@ def _validate_file(path: Path, findings: List[Finding]):
     seen_ids: set = set()
     for entry in data.get("entries") or []:
         if isinstance(entry, dict):
-            _validate_entry(entry, path, seen_ids, findings)
+            _validate_entry(entry, path, seen_ids, findings, critical_counts)
 
 
 INTAKE_GLOB = "agents/memory/intake/*.jsonl"
@@ -316,8 +407,19 @@ def main() -> int:
         else:
             print(f"ℹ️  {root} not found — nothing to validate")
         return 0
+    critical_counts: dict = {}
     for yml in sorted(root.rglob("*.yml")):
-        _validate_file(yml, findings)
+        _validate_file(yml, findings, critical_counts)
+    # Tier-0 inflation warning — soft cap on `priority: critical` per type.
+    # Council convergence (Phase 2 B2): warn rather than block, because the
+    # right answer to "too many criticals" is curator review, not CI failure.
+    for mtype, count in sorted(critical_counts.items()):
+        if count > CRITICAL_WARN_THRESHOLD:
+            findings.append(Finding(
+                f"agents/memory/{mtype}", 0, "warning",
+                f"tier-0 inflation: {count} active 'priority: critical' "
+                f"entries (threshold {CRITICAL_WARN_THRESHOLD}) — review "
+                f"whether all still warrant always-surface treatment"))
     return _emit(findings, args.format)
 
 

package/scripts/check_references.py

@@ -35,6 +35,7 @@ SCAN_DIRS = [".agent-src", "agents"]
 SKIP_DIRS = [
     "agents/roadmaps/archive",   # archived roadmaps have historical refs
     "agents/council-sessions",   # per-user audit trail (gitignored), captured provider output
+    "agents/council-responses",  # paired council output (gitignored), captured provider output
     "agents/council-questions",  # design Q&A trail — forward-refs to planned artifacts
     "agents/analysis",           # plate-comparison working docs — forward-refs to planned artifacts
 ]

package/scripts/lint_context_spine_usage.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""Context-spine usage linter.
+
+Closes the lint gap left after `scripts/schemas/skill.schema.json`
+gained the `context_spine` enum: a skill can declare
+`context_spine: [product]` in frontmatter without ever citing the
+slot in its body, and the schema check will not catch it.
+
+This linter enforces the author checklist in
+`docs/contracts/context-spine.md` § 6: for every slot declared in
+frontmatter, the skill body MUST cite the slot at least once.
+A citation is any of these tokens:
+
+  - the literal path `agents/context-spine/<slot>.md`
+  - the slot name in bold: ``**<slot>**``
+  - the slot name in inline code: `` `<slot>` ``
+
+Cap: ≤ 150 LOC, stdlib only. Hooked into `task ci` via
+`task lint-context-spine-usage`.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+QUIET = "--quiet" in sys.argv
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILL_GLOBS = (
+    ".agent-src.uncompressed/skills/**/SKILL.md",
+    ".agent-src/skills/**/SKILL.md",
+)
+VALID_SLOTS = ("product", "team", "repo")
+
+CONTEXT_SPINE_PAT = re.compile(
+    r"^context_spine:\s*\[([^\]]*)\]\s*$", re.MULTILINE
+)
+
+
+def _frontmatter_and_body(text: str) -> tuple[str, str]:
+    if not text.startswith("---\n"):
+        return "", text
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return "", text
+    return text[4:end], text[end + 5 :]
+
+
+def _read_spine(fm: str) -> list[str] | None:
+    m = CONTEXT_SPINE_PAT.search(fm)
+    if m is None:
+        return None
+    raw = m.group(1).strip()
+    if not raw:
+        return []
+    return [s.strip().strip("'\"") for s in raw.split(",") if s.strip()]
+
+
+def _slot_cited(body: str, slot: str) -> bool:
+    """A slot is cited if any of three forms appears in the body."""
+    forms = (
+        f"agents/context-spine/{slot}.md",
+        f"**{slot}**",
+        f"`{slot}`",
+    )
+    return any(form in body for form in forms)
+
+
+def lint_skill(path: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8")
+    fm, body = _frontmatter_and_body(text)
+    if not fm:
+        return []
+    slots = _read_spine(fm)
+    if slots is None:
+        return []
+    problems: list[str] = []
+    for slot in slots:
+        if slot not in VALID_SLOTS:
+            problems.append(
+                f"unknown_context_spine_slot: '{slot}' "
+                f"(valid: {', '.join(VALID_SLOTS)})"
+            )
+            continue
+        if not _slot_cited(body, slot):
+            problems.append(
+                f"declared context_spine slot '{slot}' is never cited "
+                f"in the skill body — add `**{slot}**`, `` `{slot}` ``, "
+                f"or a link to `agents/context-spine/{slot}.md` "
+                f"(see docs/contracts/context-spine.md § 6)"
+            )
+    return problems
+
+
+def main() -> int:
+    skills: list[Path] = []
+    for pattern in SKILL_GLOBS:
+        skills.extend(sorted(REPO_ROOT.glob(pattern)))
+    if not skills:
+        print("❌  no SKILL.md files matched", file=sys.stderr)
+        return 1
+    failed = 0
+    declared = 0
+    for skill in skills:
+        rel = skill.relative_to(REPO_ROOT)
+        problems = lint_skill(skill)
+        text = skill.read_text(encoding="utf-8")
+        fm, _ = _frontmatter_and_body(text)
+        if fm and CONTEXT_SPINE_PAT.search(fm):
+            declared += 1
+        if problems:
+            failed += 1
+            print(f"❌  {rel}", file=sys.stderr)
+            for p in problems:
+                print(f"    - {p}", file=sys.stderr)
+    if failed:
+        print(
+            f"\n❌  {failed} skill(s) failed context-spine usage lint "
+            f"({declared} skill(s) declare a spine)",
+            file=sys.stderr,
+        )
+        return 1
+    if not QUIET:
+        print(
+            f"✅  {declared} skill(s) declare context_spine; "
+            f"all declared slots are cited in the body"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_roadmap_complexity.py

@@ -10,7 +10,10 @@ Enforces the measurable subset of
     headings, and contain no `## Council Round N` / `### Verdict`
     sections;
   - structural roadmaps have no upper cap, but the tag must be
-    declared.
+    declared;
+  - plate / horizon framing is forbidden when
+    `roadmap.horizon_weeks` in `.agent-settings.yml` is 0 (default)
+    and allowed when it is a positive integer.
 
 Cap: ≤ 150 LOC, stdlib only. Hooked into `task ci` via
 `task lint-roadmap-complexity`.
@@ -27,6 +30,10 @@ REPO_ROOT = Path(__file__).resolve().parent.parent
 ROADMAP_GLOB = "agents/roadmaps/*.md"
 LIGHTWEIGHT_LINE_CAP = 600
 LIGHTWEIGHT_PHASE_CAP = 6
+SETTINGS_FILE = REPO_ROOT / ".agent-settings.yml"
+HORIZON_WEEKS_PAT = re.compile(
+    r"^\s*horizon_weeks:\s*(\d+)\s*(?:#.*)?$", re.MULTILINE
+)
 
 PHASE_PAT = re.compile(r"^## Phase \d+\b", re.MULTILINE)
 COUNCIL_PAT = re.compile(r"^## Council Round \d+\b", re.MULTILINE)
@@ -35,6 +42,29 @@ COMPLEXITY_PAT = re.compile(
     r"^complexity:\s*(lightweight|structural)\s*$", re.MULTILINE
 )
 
+# Plate / horizon detection — template rule 16 forbids time-boxed plates
+# in roadmaps. Patterns match the authoring devices we are retiring.
+PLATE_PATS: tuple[tuple[re.Pattern[str], str], ...] = (
+    (re.compile(r"^##\s+Horizon\b", re.MULTILINE | re.IGNORECASE),
+     "'## Horizon' section header"),
+    (re.compile(r"\b\d+-week\s+(visible\s+)?plate\b", re.IGNORECASE),
+     "'N-week (visible) plate' phrasing"),
+    (re.compile(r"\bvisible\s+plate\b", re.IGNORECASE),
+     "'visible plate' phrasing"),
+    (re.compile(r"\b(in|out)-of-plate\b", re.IGNORECASE),
+     "'in-of-plate' / 'out-of-plate' marker"),
+    (re.compile(r"\bout-of-horizon\b", re.IGNORECASE),
+     "'out-of-horizon' marker"),
+    (re.compile(r"\bIn-plate\??\b"),
+     "'In-plate' / 'In-plate?' label"),
+    (re.compile(r"\bOut-of-plate\b"),
+     "'Out-of-plate' label"),
+    (re.compile(r"inside\s+(the\s+|\d+-week\s+)?plate", re.IGNORECASE),
+     "'inside the plate' phrasing"),
+    (re.compile(r"outside\s+(the\s+|\d+-week\s+)?plate", re.IGNORECASE),
+     "'outside the plate' phrasing"),
+)
+
 
 def _frontmatter(text: str) -> str:
     if not text.startswith("---\n"):
@@ -43,6 +73,38 @@ def _frontmatter(text: str) -> str:
     return text[4:end] if end != -1 else ""
 
 
+def _read_horizon_weeks() -> int:
+    """Read roadmap.horizon_weeks from .agent-settings.yml.
+
+    Default 0 (off) when file or key is missing or unparseable.
+    Positive integer = horizon framing allowed.
+    """
+    if not SETTINGS_FILE.is_file():
+        return 0
+    try:
+        text = SETTINGS_FILE.read_text(encoding="utf-8")
+    except OSError:
+        return 0
+    in_roadmap = False
+    for raw in text.splitlines():
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            continue
+        if raw.startswith("roadmap:"):
+            in_roadmap = True
+            continue
+        if in_roadmap and raw and not raw.startswith((" ", "\t")):
+            in_roadmap = False
+            continue
+        if in_roadmap:
+            m = HORIZON_WEEKS_PAT.match(raw)
+            if m:
+                try:
+                    return max(0, int(m.group(1)))
+                except ValueError:
+                    return 0
+    return 0
+
+
 def _read_complexity(fm: str) -> str | None:
     m = COMPLEXITY_PAT.search(fm)
     return m.group(1) if m else None
@@ -73,7 +135,26 @@ def _check_lightweight(text: str, line_count: int, problems: list[str]) -> None:
         )
 
 
-def lint_roadmap(path: Path) -> list[str]:
+def _check_no_plate(text: str, problems: list[str]) -> None:
+    """Detect time-boxed plate / horizon framing.
+
+    Forbidden by template rule 16 when `roadmap.horizon_weeks` is 0
+    (default). Allowed when the setting is a positive integer.
+    """
+    for pat, label in PLATE_PATS:
+        m = pat.search(text)
+        if m is None:
+            continue
+        line = text.count("\n", 0, m.start()) + 1
+        problems.append(
+            f"plate/horizon convention detected ({label}) at line {line} — "
+            f"forbidden by templates/roadmaps.md rule 16 when "
+            f"`roadmap.horizon_weeks` is 0; set a positive integer in "
+            f".agent-settings.yml to opt in"
+        )
+
+
+def lint_roadmap(path: Path, horizon_weeks: int) -> list[str]:
     text = path.read_text(encoding="utf-8")
     line_count = text.count("\n") + (1 if text and not text.endswith("\n") else 0)
     problems: list[str] = []
@@ -87,11 +168,14 @@ def lint_roadmap(path: Path) -> list[str]:
         return problems
     if complexity == "lightweight":
         _check_lightweight(text, line_count, problems)
+    if horizon_weeks <= 0:
+        _check_no_plate(text, problems)
     return problems
 
 
 def main() -> int:
     roadmaps = sorted(REPO_ROOT.glob(ROADMAP_GLOB))
+    horizon_weeks = _read_horizon_weeks()
     if not roadmaps:
         print(f"❌  no roadmaps matched {ROADMAP_GLOB}", file=sys.stderr)
         return 1
@@ -99,7 +183,7 @@ def main() -> int:
     summary: list[tuple[str, str]] = []
     for roadmap in roadmaps:
         rel = roadmap.relative_to(REPO_ROOT)
-        problems = lint_roadmap(roadmap)
+        problems = lint_roadmap(roadmap, horizon_weeks)
         text = roadmap.read_text(encoding="utf-8")
         complexity = _read_complexity(_frontmatter(text)) or "untagged"
         summary.append((str(rel), complexity))