@event4u/agent-config 3.3.0 → 4.2.0

package/scripts/lint_ghostwriter_source.py

@@ -3,7 +3,7 @@
 
 Two storage tiers exist (see docs/contracts/ghostwriter-schema.md):
 
-  * .agent-src.uncompressed/ghostwriter/  — package source. Ships
+  * .agent-src.uncondensed/ghostwriter/  — package source. Ships
     fictional fixtures ONLY (`fictional: true`). Every file stem must
     be on scripts/ghostwriter_fixture_allowlist.txt. `aliases:` is
     forbidden here (consumer-only feature).
@@ -28,7 +28,7 @@ import yaml
 QUIET = "--quiet" in sys.argv
 
 REPO = Path(__file__).resolve().parents[1]
-PACKAGE_DIR = REPO / ".agent-src.uncompressed" / "ghostwriter"
+PACKAGE_DIR = REPO / ".agent-src.uncondensed" / "ghostwriter"
 CONSUMER_DIR = REPO / "agents" / "ghostwriter"
 ALLOWLIST = REPO / "scripts" / "ghostwriter_fixture_allowlist.txt"
 EXEMPT_STEMS = frozenset({"README"})
@@ -159,7 +159,7 @@ def lint_consumer_side() -> list[str]:
         if data.get("fictional") is True:
             errors.append(
                 f"    'fictional: true' in consumer tree: {path.relative_to(REPO)} "
-                f"— fictional fixtures belong in .agent-src.uncompressed/ghostwriter/"
+                f"— fictional fixtures belong in .agent-src.uncondensed/ghostwriter/"
             )
 
         aliases = data.get("aliases")

package/scripts/lint_handoffs.py

@@ -27,7 +27,7 @@ from typing import Iterable
 QUIET = "--quiet" in sys.argv
 
 REPO = Path(__file__).resolve().parents[1]
-SKILLS_DIR = REPO / ".agent-src.uncompressed" / "skills"
+SKILLS_DIR = REPO / ".agent-src.uncondensed" / "skills"
 
 LINK_RE = re.compile(r"\[`?([a-z0-9][a-z0-9-]*)`?\]\(([^)]+SKILL\.md)\)")
 RELATED_HEADING_RE = re.compile(r"^##\s+Related\s+Skills\s*$", re.IGNORECASE)

package/scripts/lint_load_context.py

@@ -24,37 +24,37 @@ QUIET = "--quiet" in sys.argv
 ROOT = Path(__file__).resolve().parent.parent
 
 SCAN_DIRS = [
-    ROOT / ".agent-src.uncompressed" / "rules",
-    ROOT / ".agent-src.uncompressed" / "contexts",
+    ROOT / ".agent-src.uncondensed" / "rules",
+    ROOT / ".agent-src.uncondensed" / "contexts",
     ROOT / "agents" / "contexts",
 ]
 
 ALLOWED_PREFIXES = (
     "contexts/",                               # logical name (canonical — P1.1 / P5.3)
-    ".agent-src/contexts/",                    # projected (defensive — only seen in compressed inputs)
+    ".agent-src/contexts/",                    # projected (defensive — only seen in condensed inputs)
     "agents/settings/contexts/",                        # project-local
 )
 
-# `.agent-src.uncompressed/contexts/` was the legacy fully-qualified form
+# `.agent-src.uncondensed/contexts/` was the legacy fully-qualified form
 # (pre road-to-path-fixes.md P5.3). It is now a hard error: P2.1 migrated
 # all in-tree rules to logical names, the rewriter resolves them at
-# compress time, and the schema regex in `scripts/schemas/rule.schema.json`
+# condense time, and the schema regex in `scripts/schemas/rule.schema.json`
 # rejects the prefix at validate-schema time. Keeping a separate runtime
 # diagnostic so the failure points authors at the canonical
 # `contexts/<area>/<file>.md` form rather than a generic schema mismatch.
-LEGACY_PREFIX = ".agent-src.uncompressed/contexts/"
+LEGACY_PREFIX = ".agent-src.uncondensed/contexts/"
 
 # Logical names resolve against the source root.
-SOURCE_ROOT = ROOT / ".agent-src.uncompressed"
+SOURCE_ROOT = ROOT / ".agent-src.uncondensed"
 
-PUBLIC_RULE_PREFIX = ".agent-src.uncompressed/rules/"
+PUBLIC_RULE_PREFIX = ".agent-src.uncondensed/rules/"
 PROJECT_LOCAL_PREFIX = "agents/settings/contexts/"
 
 
 def resolve_entry(entry: str) -> Path:
     """Resolve a `load_context:` entry to an absolute path on disk.
 
-    Logical names (`contexts/...`) live under `.agent-src.uncompressed/`;
+    Logical names (`contexts/...`) live under `.agent-src.uncondensed/`;
     fully-qualified entries are repo-root-relative.
     """
     if entry.startswith("contexts/"):
@@ -152,9 +152,9 @@ def main() -> int:
                 errors.append(f"{rel(f)}: entry not str ending in .md → {entry!r}")
                 continue
             if entry.startswith(LEGACY_PREFIX):
-                logical = entry[len(".agent-src.uncompressed/"):]
+                logical = entry[len(".agent-src.uncondensed/"):]
                 errors.append(
-                    f"{rel(f)}: legacy `.agent-src.uncompressed/` prefix in load_context → {entry} "
+                    f"{rel(f)}: legacy `.agent-src.uncondensed/` prefix in load_context → {entry} "
                     f"— use logical name `{logical}` instead (road-to-path-fixes.md P5.3)"
                 )
                 continue

package/scripts/lint_media_policy_linkage.py

@@ -4,9 +4,9 @@
 Every policy file under `agents/settings/policies/media/` (except README) must
 be linked from at least one of:
 
-  * a skill SKILL.md (any .agent-src.uncompressed/skills/*/SKILL.md
+  * a skill SKILL.md (any .agent-src.uncondensed/skills/*/SKILL.md
     or .claude/skills/*/SKILL.md),
-  * a routing rule under .agent-src.uncompressed/rules/, or
+  * a routing rule under .agent-src.uncondensed/rules/, or
   * a sibling policy file under agents/settings/policies/media/.
 
 A policy that no surface references is a silent policy and a silent
@@ -31,9 +31,9 @@ EXEMPT_STEMS = frozenset({"README"})
 
 # Surfaces scanned for inbound references to policy files.
 SCAN_ROOTS: tuple[Path, ...] = (
-    REPO / ".agent-src.uncompressed" / "skills",
-    REPO / ".agent-src.uncompressed" / "rules",
-    REPO / ".agent-src.uncompressed" / "commands",
+    REPO / ".agent-src.uncondensed" / "skills",
+    REPO / ".agent-src.uncondensed" / "rules",
+    REPO / ".agent-src.uncondensed" / "commands",
     REPO / ".claude" / "skills",
     REPO / "agents" / "policies" / "media",
 )

package/scripts/lint_namespace.py

@@ -10,7 +10,7 @@ import argparse, re, sys
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parent.parent
-SRC = ROOT / ".agent-src.uncompressed"
+SRC = ROOT / ".agent-src.uncondensed"
 
 # Source-of-truth regex; mirrored in docs/contracts/namespace.md § 1.
 NAME_RE = re.compile(r"^[a-z][a-z0-9]*(-[a-z0-9]+)*$")

package/scripts/lint_no_new_atomic_commands.py

@@ -3,7 +3,7 @@
 Atomic-command linter for the command-collapse policy.
 
 Reads the locked verb clusters from `docs/contracts/command-clusters.md`,
-finds every command file under `.agent-src.uncompressed/commands/` that
+finds every command file under `.agent-src.uncondensed/commands/` that
 was **added** since `--baseline` (default: `main`), and requires each
 new file to declare either:
 
@@ -32,7 +32,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 ROOT = Path(__file__).resolve().parent.parent
-COMMANDS_DIR = Path(".agent-src.uncompressed/commands")
+COMMANDS_DIR = Path(".agent-src.uncondensed/commands")
 CLUSTER_CONTRACT = Path("docs/contracts/command-clusters.md")
 
 

package/scripts/lint_orchestration_dsl.py

@@ -47,7 +47,7 @@ MAX_STEPS = 32
 MIN_STEPS = 1
 
 # Subagent-orchestration modes — kept in lock-step with
-# .agent-src.uncompressed/skills/subagent-orchestration/SKILL.md.
+# .agent-src.uncondensed/skills/subagent-orchestration/SKILL.md.
 SUBAGENT_MODES = {
     "do-and-judge", "do-and-judge-two-stage",
     "do-in-steps", "do-in-parallel", "do-in-worktrees",

package/scripts/lint_pack_boundaries.py

@@ -2,7 +2,7 @@
 """Enforce cross-pack reference boundaries.
 
 Phase 4.4 of the monorepo migration (ADR-017). Walks every markdown
-link in every artefact under ``packages/*/.agent-src.uncompressed/``
+link in every artefact under ``packages/*/.agent-src.uncondensed/``
 and verifies the link target's pack is either the same pack, ``core``
 (always allowed), or listed in the source pack's ``requires``.
 
@@ -46,7 +46,7 @@ def _build_artefact_index() -> dict[str, str]:
     for pkg in sorted(PACKAGES.iterdir()):
         if not pkg.is_dir():
             continue
-        src_root = pkg / ".agent-src.uncompressed"
+        src_root = pkg / ".agent-src.uncondensed"
         if not src_root.is_dir():
             continue
         pid = _load_pack_meta(pkg).get("id") or pkg.name.removeprefix("pack-")

package/scripts/lint_persona_governance.py

@@ -2,7 +2,7 @@
 """Lint persona governance — per-domain cap (hard) + citation floor (warn).
 
 Enforces the mechanical checks in
-`.agent-src.uncompressed/rules/persona-governance.md`:
+`.agent-src.uncondensed/rules/persona-governance.md`:
 
   1. **Per-domain cap (HARD)** — ≤ 2 active specialist personas per
      content domain. Core-tier personas are exempt. `status:
@@ -11,7 +11,7 @@ Enforces the mechanical checks in
      deletion, no soak window.
   2. **Skill citation floor (WARN)** — every active specialist
      persona SHOULD be cited by `personas: [<id>]` in at least one
-     skill SKILL.md under `.agent-src.uncompressed/skills/` or
+     skill SKILL.md under `.agent-src.uncondensed/skills/` or
      `.claude/skills/`. Surfaced as a warning, never blocks CI:
      the citation floor is enforced at PR time per the rule (a new
      specialist MUST land with a cite); pre-existing wiring debt is
@@ -39,9 +39,9 @@ from pathlib import Path
 QUIET = "--quiet" in sys.argv
 
 REPO = Path(__file__).resolve().parents[1]
-PERSONA_DIR = REPO / ".agent-src.uncompressed" / "personas"
+PERSONA_DIR = REPO / ".agent-src.uncondensed" / "personas"
 SKILL_ROOTS: tuple[Path, ...] = (
-    REPO / ".agent-src.uncompressed" / "skills",
+    REPO / ".agent-src.uncondensed" / "skills",
     REPO / ".claude" / "skills",
 )
 

package/scripts/lint_role_experiences.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""Linter for ``agents/roles/<slug>/`` role experiences.
+
+Asserts the structural floor pinned in
+``docs/contracts/role-experience.md``:
+
+  1. Every role directory has ``index.md`` + ``skills.yml``.
+  2. ``index.md`` carries all required frontmatter keys (``role``,
+     ``display_name``, ``tagline``, ``recommended_packs``,
+     ``install_path_hint``, ``recruit_session_ref``, ``status``).
+  3. ``index.md`` body declares at least three first tasks (per
+     ``## Three first tasks`` heading + numbered list).
+  4. ``prompts/`` contains at least five prompts (per the roadmap's
+     Phase B Step 6 acceptance — ``≥ 5 prompts per role``).
+  5. Every prompt under ``prompts/<name>.md`` carries the four
+     required frontmatter keys (``name``, ``intent``, ``inputs``,
+     ``output_shape``) plus ``skill_hint``.
+  6. Every ``skills.yml`` skill ``id`` resolves to an existing skill
+     under ``.agent-src.uncondensed/skills/<id>/`` or
+     ``.agent-src/skills/<id>/`` (condensed projection counts).
+
+The roadmap step is intentionally opt-in for CI — the existing
+``task ci`` wiring is the caller's concern; this script is the
+mechanical floor it can wrap.
+
+Phase B Step 6 of ``road-to-frictionless-employee-workspace.md``.
+Adds a ``--plain-language`` mode for Phase C Step 5 that scans the
+role indices for jargon listed in
+``docs/contracts/plain-language-surface.md`` and flags any hit.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+ROLES_DIR = ROOT / "agents" / "roles"
+SKILL_SOURCES = [
+    ROOT / ".agent-src.uncondensed" / "skills",
+    ROOT / ".agent-src" / "skills",
+]
+
+REQUIRED_INDEX_KEYS = {
+    "role",
+    "display_name",
+    "tagline",
+    "recommended_packs",
+    "install_path_hint",
+    "recruit_session_ref",
+    "status",
+}
+
+REQUIRED_PROMPT_KEYS = {"name", "intent", "inputs", "output_shape", "skill_hint"}
+
+MIN_FIRST_TASKS = 3
+MIN_PROMPTS_PER_ROLE = 5
+
+FRONTMATTER_RE = re.compile(r"^---\r?\n(.*?)\r?\n---\r?\n", re.DOTALL)
+TASK_HEADING_RE = re.compile(r"^## Three first tasks\s*$", re.MULTILINE)
+TASK_ITEM_RE = re.compile(r"^\s*\d+\.\s+\*\*[^*]+\*\*", re.MULTILINE)
+
+# Jargon list mirrors docs/contracts/plain-language-surface.md.
+PLAIN_LANGUAGE_JARGON = [
+    "council",
+    "trust level",
+    "pack",
+    "orchestration",
+    "contract",
+    "advisory",
+]
+
+
+def parse_frontmatter(text: str) -> tuple[dict, str]:
+    m = FRONTMATTER_RE.match(text)
+    if m is None:
+        return {}, text
+    try:
+        loaded = yaml.safe_load(m.group(1)) or {}
+    except yaml.YAMLError:
+        return {}, text[m.end():]
+    if not isinstance(loaded, dict):
+        return {}, text[m.end():]
+    return loaded, text[m.end():]
+
+
+def count_first_tasks(body: str) -> int:
+    heading_match = TASK_HEADING_RE.search(body)
+    if heading_match is None:
+        return 0
+    # Slice from heading to the next "## " heading (or end of file).
+    after = body[heading_match.end():]
+    next_section = re.search(r"^## ", after, re.MULTILINE)
+    section = after[: next_section.start()] if next_section else after
+    return len(TASK_ITEM_RE.findall(section))
+
+
+def all_skills() -> set[str]:
+    found: set[str] = set()
+    for src in SKILL_SOURCES:
+        if not src.exists():
+            continue
+        for child in src.iterdir():
+            if child.is_dir():
+                found.add(child.name)
+    return found
+
+
+def lint_role(role_dir: Path, known_skills: set[str], failures: list[str]) -> None:
+    slug = role_dir.name
+    if slug.startswith(("_", ".")):
+        return
+
+    index_path = role_dir / "index.md"
+    skills_path = role_dir / "skills.yml"
+
+    if not index_path.exists():
+        failures.append(f"{role_dir}: missing index.md")
+        return
+    if not skills_path.exists():
+        failures.append(f"{role_dir}: missing skills.yml")
+        return
+
+    fm, body = parse_frontmatter(index_path.read_text(encoding="utf-8"))
+    missing_keys = REQUIRED_INDEX_KEYS - set(fm)
+    if missing_keys:
+        failures.append(
+            f"{index_path}: missing frontmatter keys: {sorted(missing_keys)}"
+        )
+
+    first_tasks = count_first_tasks(body)
+    if first_tasks < MIN_FIRST_TASKS:
+        failures.append(
+            f"{index_path}: requires ≥ {MIN_FIRST_TASKS} first tasks, found {first_tasks}"
+        )
+
+    prompts_dir = role_dir / "prompts"
+    prompts = sorted(prompts_dir.glob("*.md")) if prompts_dir.exists() else []
+    if len(prompts) < MIN_PROMPTS_PER_ROLE:
+        failures.append(
+            f"{role_dir}: requires ≥ {MIN_PROMPTS_PER_ROLE} prompts in prompts/, "
+            f"found {len(prompts)}"
+        )
+
+    for prompt_path in prompts:
+        prompt_fm, _ = parse_frontmatter(prompt_path.read_text(encoding="utf-8"))
+        missing = REQUIRED_PROMPT_KEYS - set(prompt_fm)
+        if missing:
+            failures.append(
+                f"{prompt_path}: missing frontmatter keys: {sorted(missing)}"
+            )
+
+    try:
+        skills_doc = yaml.safe_load(skills_path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as exc:
+        failures.append(f"{skills_path}: malformed YAML ({exc})")
+        return
+    skill_entries = skills_doc.get("skills", [])
+    if not isinstance(skill_entries, list):
+        failures.append(f"{skills_path}: `skills:` must be a list")
+        return
+    for entry in skill_entries:
+        if not isinstance(entry, dict):
+            failures.append(f"{skills_path}: skill entry is not a mapping: {entry!r}")
+            continue
+        skill_id = entry.get("id")
+        if not isinstance(skill_id, str):
+            failures.append(f"{skills_path}: skill entry missing `id`: {entry!r}")
+            continue
+        if known_skills and skill_id not in known_skills:
+            failures.append(
+                f"{skills_path}: skill `{skill_id}` does not resolve to an existing skill"
+            )
+
+
+def lint_plain_language(failures: list[str]) -> None:
+    """Scan each role's index.md for the six jargon terms; flag hits.
+
+    Skipped sections: frontmatter, fenced code blocks. Role-experience
+    index files are the non-developer surface and must not leak the
+    package's internal vocabulary.
+    """
+    for role_dir in sorted(ROLES_DIR.iterdir()):
+        if not role_dir.is_dir() or role_dir.name.startswith(("_", ".")):
+            continue
+        index_path = role_dir / "index.md"
+        if not index_path.exists():
+            continue
+        _, body = parse_frontmatter(index_path.read_text(encoding="utf-8"))
+        # Strip fenced code blocks.
+        body_stripped = re.sub(r"```[\s\S]*?```", "", body)
+        for term in PLAIN_LANGUAGE_JARGON:
+            pattern = re.compile(rf"\b{re.escape(term)}\b", re.IGNORECASE)
+            if pattern.search(body_stripped):
+                failures.append(
+                    f"{index_path}: contains the jargon term `{term}` "
+                    f"(see docs/contracts/plain-language-surface.md)"
+                )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="lint_role_experiences")
+    parser.add_argument(
+        "--plain-language",
+        action="store_true",
+        help="Additionally scan role indices for jargon listed in "
+        "docs/contracts/plain-language-surface.md.",
+    )
+    args = parser.parse_args(argv)
+
+    if not ROLES_DIR.exists():
+        print(f"lint_role_experiences: roles dir not found at {ROLES_DIR}")
+        return 0
+
+    known_skills = all_skills()
+    failures: list[str] = []
+    for role_dir in sorted(ROLES_DIR.iterdir()):
+        if role_dir.is_dir():
+            lint_role(role_dir, known_skills, failures)
+
+    if args.plain_language:
+        lint_plain_language(failures)
+
+    if failures:
+        for f in failures:
+            print(f"❌ {f}")
+        print(f"\nlint_role_experiences: {len(failures)} failure(s)")
+        return 1
+    print("✅ lint_role_experiences: all role experiences pass")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_rule_interactions.py

@@ -3,7 +3,7 @@
 
 Validates:
   - Schema (required fields per pair)
-  - All rule slugs in `rules:` exist as `.agent-src.uncompressed/rules/<slug>.md`
+  - All rule slugs in `rules:` exist as `.agent-src.uncondensed/rules/<slug>.md`
   - Every pair references rules listed in the top-level `rules:` block
   - `relation` is one of the allowed values
   - All `evidence:` entries point at real files (anchors are advisory, not checked)
@@ -38,7 +38,7 @@ def _rule_exists(slug: str) -> bool:
 def _evidence_exists(file_part: str) -> bool:
     """Return True if the evidence path resolves under any source root.
 
-    Accepts legacy ``.agent-src.uncompressed/...`` citations and resolves
+    Accepts legacy ``.agent-src.uncondensed/...`` citations and resolves
     them through the multi-root layout; falls back to a literal repo
     path check for non-source citations (docs/, agents/, ...).
     """

package/scripts/lint_rule_tiers.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Lint rule frontmatter for the `tier:` key.
 
-Hard-fails CI if any rule under .agent-src.uncompressed/rules/ lacks a
+Hard-fails CI if any rule under .agent-src.uncondensed/rules/ lacks a
 `tier:` declaration or uses an unknown tier value. The valid tier set is
 locked by agents/settings/contexts/hardening-pattern.md and the matrix in
 agents/settings/contexts/rule-trigger-matrix.md.

package/scripts/lint_trust_coherence.py

@@ -33,7 +33,7 @@ COMPILED_SRC = ROOT / ".agent-src"
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from _lib.agent_src import strip_source_prefix  # noqa: E402
 
-# Imported lazily inside _banner_marker() to keep the cap loose if compress.py
+# Imported lazily inside _banner_marker() to keep the cap loose if condense.py
 # grows additional top-level side effects.
 _BANNER_MARKER = "<!-- agent-config:human-review-banner -->"
 
@@ -118,7 +118,7 @@ def _check_human_review_banners(
             errs.append(
                 f"{rel}: human_review_required=true but compiled output"
                 f" `{compiled.relative_to(ROOT)}` is missing the HRR banner"
-                f" (`{_BANNER_MARKER}`) — re-run `task compress`."
+                f" (`{_BANNER_MARKER}`) — re-run `task condense`."
             )
     return errs