@jenga-ai/agent 3.5.0 → 4.0.0

package/skills/jenga/scripts/run-playbook-step.sh

@@ -181,6 +181,18 @@
 #       stdout). If that was the last step, emits a completion report instead (see OUTPUT SCHEMA)
 #       and removes the state file.
 #
+#       RUNTIME TYPE VERIFICATION (E62_S02_T01): when a value IS given, it is checked against the
+#       CURRENT step's declared `output_types` (read off that step's own SKILL.md), via
+#       `scripts/validate-typed-object.sh` -- normalizing first, then re-checking, before any
+#       failure is declared. A `{when, type}` conditional declaration conforms if it satisfies AT
+#       LEAST ONE branch (no classifier is ever run, no branch state is tracked). A value that
+#       still does not conform after normalize is NOT stored -- this call is silently redirected
+#       into the exact same halt behavior as `advance <state_file> failed "<note>"` (see below),
+#       with a note naming the step, the declared type(s) checked, and the raw pre-normalization
+#       value. A step with no declared `output_types` (including one this call cannot resolve a
+#       SKILL.md for) is completely unaffected: no lookup is even attempted beyond determining
+#       there is nothing to check.
+#
 #   run-playbook-step.sh advance <state_file> skipped
 #       Records the CURRENT step as SKIPPED (a new `skipped` list, distinct from `completed`) and
 #       advances the pointer exactly like `passed` -- a skipped step never halts the chain and is
@@ -597,6 +609,30 @@ elif [ "$SUBCOMMAND" = "advance" ]; then
 
   PROJECT_DIR="$(resolve_project_dir)"
 
+  # --- E62_S02_T01: resolve the jenga-agent PACKAGE root, needed ONLY to look up a completing
+  # step's declared `output_types` off its SKILL.md for runtime type verification. Mirrors
+  # load-playbooks.sh's own PKG_ROOT resolution (monorepo checkout vs. installed npm package) --
+  # including reusing JENGA_PLAYBOOKS_TEST_ROOT verbatim as the SAME test-injection override, rather
+  # than inventing a second env var for the same concept. Deliberately gated on
+  # `OUTCOME = passed && EXTRA non-empty`: those are the ONLY two conditions under which
+  # verification does anything at all (see the no-op cases in this task's board item), so a
+  # `skipped`/`failed` call, or a `passed` call with no typed-output value, never pays for this
+  # resolution at all -- "no lookup even attempted beyond determining there is nothing to check."
+  PKG_ROOT=""
+  if [ "$OUTCOME" = "passed" ] && [ -n "$EXTRA" ]; then
+    ADVANCE_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    if [ -n "${JENGA_PLAYBOOKS_TEST_ROOT:-}" ]; then
+      PKG_ROOT="$JENGA_PLAYBOOKS_TEST_ROOT"
+    elif [ -d "$ADVANCE_SCRIPT_DIR/../../../templates" ]; then
+      PKG_ROOT="$(cd "$ADVANCE_SCRIPT_DIR/../../.." && pwd)"
+    elif [ -d "$PROJECT_DIR/node_modules/@jenga-ai/agent/templates" ]; then
+      PKG_ROOT="$PROJECT_DIR/node_modules/@jenga-ai/agent"
+    else
+      echo "Error: could not locate the jenga-agent package root (templates/ not found via monorepo checkout or node_modules/@jenga-ai/agent) -- cannot resolve output_types for step verification." >&2
+      exit 2
+    fi
+  fi
+
   PY_SCRIPT="$(mktemp -t run-playbook-step-advance-XXXXXX.py)"
   trap 'rm -f "$PY_SCRIPT"' EXIT
 
@@ -604,7 +640,9 @@ elif [ "$SUBCOMMAND" = "advance" ]; then
 import json
 import os
 import re
+import subprocess
 import sys
+import tempfile
 from datetime import datetime, timezone
 
 state_file_path = sys.argv[1]
@@ -615,6 +653,221 @@ outcome = sys.argv[2]
 extra = sys.argv[3] if len(sys.argv) > 3 and sys.argv[3] != "" else None
 note = extra
 project_dir = sys.argv[4] if len(sys.argv) > 4 and sys.argv[4] != "" else None
+# E62_S02_T01: the jenga-agent package root, resolved (or hard-errored) by the bash wrapper above,
+# ONLY when outcome == "passed" and extra is non-empty. Empty string in every other case -- exactly
+# the cases where verification is a documented no-op, so this is never even looked at.
+pkg_root = sys.argv[5] if len(sys.argv) > 5 and sys.argv[5] != "" else None
+
+# ---------------------------------------------------------------------------------------------
+# E62_S02_T01: runtime type verification at the "passed" chokepoint
+# ---------------------------------------------------------------------------------------------
+# `extract_output_types`/`declared_type_entries` below are a DELIBERATE, DOCUMENTED duplication of
+# skills/jenga/scripts/load-playbooks.sh's own `extract_types_field`/`extract_output_types`/
+# `declared_type_entries` (see that script's "TYPE REGISTRY" section, around line 788 as of
+# E62_S01_T04). The task considered factoring this into a shared, importable module, but every
+# python body in both scripts is a throwaway file generated into a fresh `mktemp` path per
+# invocation (see the `cat > "$PY_SCRIPT" <<'PY'` pattern this whole file uses) -- there is no
+# existing precedent in this repo for a shared importable python module fed to that pattern, and
+# building one purely for a ~30-line, rarely-changing frontmatter parser was judged riskier than a
+# small, clearly-labelled duplicate. If this parser ever needs a THIRD copy, that is the signal to
+# extract it for real; until then, a change to one copy's parsing rules should always be checked
+# against the other by anyone touching either.
+_FRONTMATTER_RE = re.compile(r'^---\r?\n(.*?)\r?\n---', re.DOTALL)
+
+
+def extract_output_types(skill_md_path):
+    """Best-effort extraction of the `output_types` frontmatter field from a SKILL.md. Returns
+    None if the file/field is missing or unparseable, a `str` for the single-static-type form, or
+    a `list[dict]` for the `{when, type}` list form. Mirrors load-playbooks.sh's
+    `extract_types_field(path, "output_types")` exactly -- see the module-level note above."""
+    try:
+        with open(skill_md_path, encoding="utf-8") as fh:
+            content = fh.read()
+    except OSError:
+        return None
+
+    fm_match = _FRONTMATTER_RE.match(content)
+    if not fm_match:
+        return None
+
+    fm_lines = fm_match.group(1).splitlines()
+
+    for i, line in enumerate(fm_lines):
+        key_match = re.match(r'^output_types:\s*(.*)$', line)
+        if not key_match:
+            continue
+
+        rest = key_match.group(1).strip()
+        if rest:
+            return rest.strip('"\'')
+
+        # Block/list form: gather subsequent, more-indented lines into a list of dicts.
+        items = []
+        current = {}
+        j = i + 1
+        while j < len(fm_lines):
+            raw_line = fm_lines[j]
+            if not raw_line.strip():
+                j += 1
+                continue
+            if not raw_line[0].isspace():
+                break  # a new top-level frontmatter key ends this block
+
+            stripped = raw_line.strip()
+            item_match = re.match(r'^-\s*(.*)$', stripped)
+            if item_match:
+                if current:
+                    items.append(current)
+                current = {}
+                remainder = item_match.group(1)
+                kv = re.match(r'^([a-zA-Z_]+):\s*(.*)$', remainder) if remainder else None
+                if kv:
+                    current[kv.group(1)] = kv.group(2).strip().strip('"\'')
+            else:
+                kv = re.match(r'^([a-zA-Z_]+):\s*(.*)$', stripped)
+                if kv:
+                    current[kv.group(1)] = kv.group(2).strip().strip('"\'')
+            j += 1
+
+        if current:
+            items.append(current)
+        return items if items else None
+
+    return None
+
+
+def declared_type_entries(value):
+    """Normalize an `output_types` value into `[(type_or_None, when_or_None), ...]`. Mirrors
+    load-playbooks.sh's `declared_type_entries` exactly -- see the module-level note above."""
+    if not value:
+        return []
+    if isinstance(value, str):
+        return [(value, None)]
+    if isinstance(value, list):
+        entries = []
+        for item in value:
+            if isinstance(item, dict):
+                entries.append((item.get("type") or None, item.get("when") or None))
+            else:
+                entries.append((None, None))
+        return entries
+    return []
+
+
+def verify_typed_output(step_name, raw_value, pkg_root_dir):
+    """The E62_S02_T01 chokepoint check itself.
+
+    Returns `(failure_note_or_None, resolved_value)`:
+      - `(None, value)`     -- conforms (or nothing declared/checkable -- a no-op). `value` is the
+                               raw value unless a declared branch needed normalization to conform,
+                               in which case it is that branch's normalized value.
+      - `(note, None)`      -- every declared branch is non-conforming even after normalize. `note`
+                               names the step, the declared type(s) checked, and the raw
+                               pre-normalization value, for the existing `failed` -> `halted` path.
+
+    The conditional `{when, type}` rule (ratified at epic level, not re-derived here): the value
+    conforms if it satisfies AT LEAST ONE declared branch. No classifier script is ever run and no
+    branch state is tracked -- every declared type is checked against the SAME captured value.
+    """
+    skill_md_path = os.path.join(pkg_root_dir, "skills", step_name, "SKILL.md")
+    if not os.path.isfile(skill_md_path):
+        # No resolvable skill dir (e.g. a synthetic/test step name, or a stale board reference) --
+        # nothing to check against. Not this chokepoint's problem to diagnose further.
+        return None, raw_value
+
+    declared = extract_output_types(skill_md_path)
+    entries = [e for e in declared_type_entries(declared) if e[0] is not None]
+    if not entries:
+        # No declared output_types (or only malformed entries, which is a load-time concern this
+        # chokepoint does not re-litigate) -- a documented no-op, exactly as today.
+        return None, raw_value
+
+    validator = os.path.join(pkg_root_dir, "scripts", "validate-typed-object.sh")
+    if not os.path.isfile(validator):
+        print(
+            f"Error: type registry validator not found at {validator} -- cannot verify step "
+            f"'{step_name}'s declared output_types.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    types_checked = []
+    branch_reasons = []
+    normalized_fallback = None  # first branch that conforms only after normalize
+
+    for type_name, when_val in entries:
+        if type_name not in types_checked:
+            types_checked.append(type_name)
+
+        tmp_path = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode="w", encoding="utf-8", delete=False, prefix="run-playbook-step-verify-"
+            ) as tmp:
+                tmp.write(raw_value)
+                tmp_path = tmp.name
+            proc = subprocess.run(
+                [validator, "--value-file", tmp_path, type_name],
+                capture_output=True,
+                text=True,
+            )
+        finally:
+            if tmp_path is not None:
+                try:
+                    os.unlink(tmp_path)
+                except OSError:
+                    pass
+
+        if proc.returncode == 0:
+            # Conforms as given, under this branch alone -- the strongest possible verdict.
+            # "At least one branch accepts it" is satisfied immediately; stop checking further
+            # branches and never report this as normalized.
+            return None, raw_value
+        if proc.returncode == 2:
+            if normalized_fallback is None:
+                try:
+                    payload = json.loads(proc.stdout)
+                    normalized_fallback = payload.get("value")
+                except (json.JSONDecodeError, AttributeError):
+                    normalized_fallback = raw_value
+            continue
+        if proc.returncode == 3:
+            reason = None
+            try:
+                payload = json.loads(proc.stdout)
+                reason = payload.get("reason")
+            except (json.JSONDecodeError, AttributeError):
+                reason = None
+            branch = f" (when='{when_val}')" if when_val else ""
+            branch_reasons.append(f"type '{type_name}'{branch}: {reason or 'does not conform'}")
+            continue
+        # Exit 4 (unknown type), 5 (environment), 6 (registry contract violation) are
+        # ENVIRONMENT-level failures, never value judgments -- E62_S01_T02's own validator
+        # contract is explicit that these must not be conflated with non-conforming. A properly
+        # loaded chain should never reach an unknown/malformed type here (load-playbooks.sh's own
+        # load-time check, E62_S01_T04, already rejects that at confirmation time) -- if it
+        # happens anyway, this is a broken environment, not a playbook-author's bad value, so it
+        # is NOT routed through the failed/halted board mechanism.
+        print(
+            f"Error: scripts/validate-typed-object.sh reported an environment-level failure "
+            f"(exit {proc.returncode}) verifying step '{step_name}'s declared type '{type_name}': "
+            f"{proc.stderr.strip() or proc.stdout.strip()}",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    if normalized_fallback is not None:
+        # No branch conformed as given, but at least one conforms after its own normalize.
+        return None, normalized_fallback
+
+    # No declared branch accepts the value, as given or normalized.
+    types_list = ", ".join(types_checked)
+    detail = "; ".join(branch_reasons) if branch_reasons else "no declared branch accepts it"
+    failure_note = (
+        f"step '{step_name}' produced a value that does not conform to its declared "
+        f"output_types [{types_list}] (raw value: '{raw_value}'); {detail}"
+    )
+    return failure_note, None
 
 # --- E53_S04_T05: artifact persistence + redaction (persisted copy only -- see header) ---
 _ABS_PATH_RE = re.compile(r'(/[^\s"\']+)')
@@ -693,6 +946,19 @@ if idx >= len(steps):
 current_step = steps[idx]
 state.setdefault("skipped", [])
 
+# E62_S02_T01: verify a "passed" step's typed-output value against its declared output_types
+# BEFORE the outcome dispatch below, so a non-conforming value can redirect into the EXISTING
+# `outcome == "failed"` branch immediately after -- no second failure mechanism is introduced.
+# Both no-op cases (no declared output_types; no typed-output value at all) leave `outcome` and
+# `extra` untouched, so this is byte-for-byte the pre-existing behavior for them.
+if outcome == "passed" and extra is not None:
+    verify_failure_note, resolved_value = verify_typed_output(current_step, extra, pkg_root)
+    if verify_failure_note is not None:
+        outcome = "failed"
+        note = verify_failure_note
+    else:
+        extra = resolved_value
+
 if outcome == "failed":
     state["halted"] = True
     state["failed_step"] = current_step
@@ -757,7 +1023,7 @@ print(json.dumps({
 print(f"STATE_FILE: {state_file_path}", file=sys.stderr)
 PY
 
-  python3 "$PY_SCRIPT" "$STATE_FILE" "$OUTCOME" "$EXTRA" "$PROJECT_DIR"
+  python3 "$PY_SCRIPT" "$STATE_FILE" "$OUTCOME" "$EXTRA" "$PROJECT_DIR" "$PKG_ROOT"
   exit $?
 
 else

package/templates/SCRUM_BOARD_SCHEMA.md

@@ -297,7 +297,7 @@ currently gates on its presence.
 
 ### `[SPIKE]` — Bounded Research
 
-**Scope:** story and task level only.
+**Scope:** story and task level, **and rapports** (extended by `E35_S03_T01`, see below).
 
 **Meaning:** a time-boxed research or exploration effort whose output is a decision, a design note,
 or an answered question — **not** shippable implementation code. Existing usage (`E06_S03_spike-editable-board.md`,
@@ -312,6 +312,19 @@ or an answered question — **not** shippable implementation code. Existing usag
 `[SPIKE]` predates this document; this section formalizes an existing informal convention rather
 than introducing new behavior.
 
+**Rapport scope extension (`E35_S03_T01`):** `[SPIKE]` also applies to a problem rapport (see
+`project/rapports/problems/`) via the same title-text convention — a `[SPIKE] <Topic>` prefix on
+the rapport's own title/header field, not a frontmatter key (rapports don't carry board
+frontmatter at all). This marks a rapport as itself surfacing a bounded research question or a
+distinct idea worth tracking, independent of whatever problem the rapport was originally filed
+to report. In practice this happens as part of the idea-lifecycle outcome-record mechanism
+(`E35_S03`): when a `project/ideas.md` entry that originated from a rapport (see
+`skills/idea/SKILL.md`'s "Source-Rapport Link Convention") is later promoted or rejected, the
+outcome-record step updates that rapport with the decision and prefixes its title `[SPIKE]` if
+it isn't already tagged. As with the story/task usage above, this is advisory only — nothing
+validates or enforces the prefix's presence, and a rapport's normal `Type:`/`Related
+Epic/Story/Task` fields (per `templates/PROBLEM_RAPPORT_TEMPLATE.md`) are unaffected by it.
+
 ### `[ARCH]` — Durable Architectural Inventory
 
 **Scope:** epic, story, and task level. This is the **first tag extended to epic level** — `[SPIKE]`

package/templates/SKILL_TEMPLATE.md

@@ -3,8 +3,20 @@ name: <skill-name>
 description: <One-sentence description of what this skill does and when to use it.>
 metadata:
   prefered_agent: <agent-name>   # optional — remove if not applicable
+output_types: <type>             # optional — forwardable output type(s) this skill produces; a single
+                                 #   type string or a list of {when, type} entries. Declare only if this
+                                 #   skill genuinely produces output a playbook step could consume
+                                 #   (honesty over breadth, E53_S11). Remove if not applicable.
+input_types: <type>              # optional — forwarded input type(s) this skill accepts; same two
+                                 #   shapes as output_types. May be broadly declared — honesty over
+                                 #   breadth is scoped to output_types only (E62_S01_T03).
+                                 #   Remove if not applicable.
 ---
 
+> Type values come from the canonical vocabulary in `templates/playbook-types.json`. See
+> `docs/skill-authoring.md`'s `output_types` and `input_types` sections for the full contract,
+> including the `text` rule and the normalize-versus-convert boundary.
+
 # <Skill Title> — <Short tagline>
 
 ## Instructions

package/templates/permission-levels/level-1-locked.json

@@ -41,7 +41,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NAME=$(jq -r '.name')\n. \"$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh\"\nDIR=\"$JENGA_PROJECT_DIR/.claude/worktrees/$NAME\"\ngit worktree add \"$DIR\" -b \"$NAME\" 2>&1\necho \"$DIR\"\n"
+            "command": "NAME=$(jq -r '.name')\n. \"$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh\"\nDIR=\"$JENGA_PROJECT_DIR/.claude/worktrees/$NAME\"\ngit worktree add \"$DIR\" -b \"$NAME\" 2>&1\n\"$(git rev-parse --show-toplevel)/scripts/install-worktree-commit-guard.sh\" \"$DIR\" \"$NAME\" 1>&2\necho \"$DIR\"\n"
           }
         ]
       }

package/templates/permission-levels/level-2-guarded.json

@@ -34,7 +34,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NAME=$(jq -r '.name')\n. \"$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh\"\nDIR=\"$JENGA_PROJECT_DIR/.claude/worktrees/$NAME\"\ngit worktree add \"$DIR\" -b \"$NAME\" 2>&1\necho \"$DIR\"\n"
+            "command": "NAME=$(jq -r '.name')\n. \"$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh\"\nDIR=\"$JENGA_PROJECT_DIR/.claude/worktrees/$NAME\"\ngit worktree add \"$DIR\" -b \"$NAME\" 2>&1\n\"$(git rev-parse --show-toplevel)/scripts/install-worktree-commit-guard.sh\" \"$DIR\" \"$NAME\" 1>&2\necho \"$DIR\"\n"
           }
         ]
       }

package/templates/permission-levels/level-3-standard.json

@@ -32,7 +32,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NAME=$(jq -r '.name')\n. \"$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh\"\nDIR=\"$JENGA_PROJECT_DIR/.claude/worktrees/$NAME\"\ngit worktree add \"$DIR\" -b \"$NAME\" 2>&1\necho \"$DIR\"\n"
+            "command": "NAME=$(jq -r '.name')\n. \"$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh\"\nDIR=\"$JENGA_PROJECT_DIR/.claude/worktrees/$NAME\"\ngit worktree add \"$DIR\" -b \"$NAME\" 2>&1\n\"$(git rev-parse --show-toplevel)/scripts/install-worktree-commit-guard.sh\" \"$DIR\" \"$NAME\" 1>&2\necho \"$DIR\"\n"
           }
         ]
       }

package/templates/permission-levels/level-4-elevated.json

@@ -6,7 +6,7 @@
   "autoMode": {
     "allow": [
       "$defaults",
-      "Bash(bash skills/mirror-public/scripts/mirror.sh*)"
+      "Bash(bash skills/j-mirror-public/scripts/mirror.sh*)"
     ]
   },
   "permissions": {
@@ -30,7 +30,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NAME=$(jq -r '.name')\n. \"$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh\"\nDIR=\"$JENGA_PROJECT_DIR/.claude/worktrees/$NAME\"\ngit worktree add \"$DIR\" -b \"$NAME\" 2>&1\necho \"$DIR\"\n"
+            "command": "NAME=$(jq -r '.name')\n. \"$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh\"\nDIR=\"$JENGA_PROJECT_DIR/.claude/worktrees/$NAME\"\ngit worktree add \"$DIR\" -b \"$NAME\" 2>&1\n\"$(git rev-parse --show-toplevel)/scripts/install-worktree-commit-guard.sh\" \"$DIR\" \"$NAME\" 1>&2\necho \"$DIR\"\n"
           }
         ]
       }

package/templates/permission-levels/level-5-unrestricted.json

@@ -6,7 +6,7 @@
   "autoMode": {
     "allow": [
       "$defaults",
-      "Bash(bash skills/mirror-public/scripts/mirror.sh*)"
+      "Bash(bash skills/j-mirror-public/scripts/mirror.sh*)"
     ]
   },
   "permissions": {
@@ -28,7 +28,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NAME=$(jq -r '.name')\n. \"$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh\"\nDIR=\"$JENGA_PROJECT_DIR/.claude/worktrees/$NAME\"\ngit worktree add \"$DIR\" -b \"$NAME\" 2>&1\necho \"$DIR\"\n"
+            "command": "NAME=$(jq -r '.name')\n. \"$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh\"\nDIR=\"$JENGA_PROJECT_DIR/.claude/worktrees/$NAME\"\ngit worktree add \"$DIR\" -b \"$NAME\" 2>&1\n\"$(git rev-parse --show-toplevel)/scripts/install-worktree-commit-guard.sh\" \"$DIR\" \"$NAME\" 1>&2\necho \"$DIR\"\n"
           }
         ]
       }

package/templates/playbook-types.json

@@ -1,8 +1,42 @@
 {
-  "_comment": "Canonical playbook output-type vocabulary for Epic E53's Playbooks v2 StepObject/output_types contract (E53_S03_T02). Extend this vocabulary by adding entries to the 'types' array below -- NEVER by code changes; skills/jenga/scripts/load-playbooks.sh references this file by name in its own header contract (see that script's 'TYPE REGISTRY' section). Governed by the Scrum Master: registry additions/changes route through the normal board-item process rather than an ungoverned edit to this file -- see docs/skill-authoring.md's 'Playbook Type Registry Governance' section for the full policy.",
-  "types": [
-    "text",
-    "id_list",
-    "file_list"
-  ]
+  "_comment": "Canonical playbook type registry for Epic E53's Playbooks v2 StepObject/output_types contract (E53_S03_T02), converted from a bare list of type names into a map of type descriptors by E62_S01_T01. -- FORMAT: 'types' maps each type name to a descriptor object {\"verify\": <rule-object|null>, \"normalize\": [<transform-name>, ...]}. Both members are optional in the sense that 'verify' may be null and 'normalize' may be empty; a descriptor never carries any other key. -- VERIFY: null means the type has no checkable shape and runtime verification is a deliberate no-op. Otherwise it is an object whose keys are drawn ONLY from the enumerated 'verify_rules' below. The single rule kind defined today is 'per_line': a regex that every element of the normalized value must match. Regexes here are POSIX ERE, not PCRE -- write [0-9] and [^[:space:]], never \\d or \\S -- because the consuming validator is a shell script (E62_S01_T02). -- NORMALIZE: an ordered list of named transforms applied left to right BEFORE verification. The value is treated as a list of lines; 'split_on_comma' further splits each element on commas, 'trim' strips leading and trailing whitespace from each element, 'drop_empty' removes elements that are empty after trimming. Every entry MUST be a bare identifier matching ^[a-z][a-z0-9_]*$ AND a member of 'normalize_vocabulary' below. That closure is the single most important property of this format: because an entry cannot contain whitespace, a free-text or semantic-extraction instruction (e.g. 'extract the ids the skill meant to return') is STRUCTURALLY UNREPRESENTABLE here, not merely discouraged. LLM-driven auto-conversion and a type-repair skill were both rejected at epic level (E62); a transform name the validator does not implement is a hard error, never a string for anything to interpret. -- THE 'text' RULE: 'text' carries \"verify\": null because prose has no checkable shape. This is NOT a licence to treat 'text' as an 'any' in the load-time compatibility lattice. Unverifiable at runtime: yes. Universal acceptor at load time: no -- a universal acceptor would make every text-declaring skill compatible with everything, disarming exactly what E53_S11's honesty-over-breadth policy protects. -- EXTENDING: adding a TYPE is a DATA-ONLY edit and NEVER a code change -- add a key to 'types' whose verify/normalize are composed from the already-enumerated 'verify_rules' and 'normalize_vocabulary'. Adding a new TRANSFORM or a new RULE KIND is the one thing that does require code, since the validator has to implement it; extend the corresponding enumeration here in that same change. Removing or renaming an existing type is a breaking change: it invalidates every SKILL.md declaring it. skills/jenga/scripts/load-playbooks.sh references this file by name in its own header contract (see that script's 'TYPE REGISTRY' section). -- GOVERNANCE: owned by the Scrum Master. Registry additions or changes route through the normal board-item process rather than an ungoverned edit to this file -- see docs/skill-authoring.md's 'Playbook Type Registry Governance' section for the full policy.",
+  "verify_rules": [
+    "per_line"
+  ],
+  "normalize_vocabulary": [
+    "split_on_comma",
+    "trim",
+    "drop_empty"
+  ],
+  "types": {
+    "text": {
+      "verify": null,
+      "normalize": []
+    },
+    "id_list": {
+      "verify": {
+        "per_line": "^E[0-9]+(_S[0-9]+(_T[0-9]+)?)?$"
+      },
+      "normalize": [
+        "split_on_comma",
+        "trim",
+        "drop_empty"
+      ]
+    },
+    "file_list": {
+      "verify": {
+        "per_line": "^[^[:space:]]"
+      },
+      "normalize": [
+        "trim",
+        "drop_empty"
+      ]
+    },
+    "ranked_list": {
+      "verify": {
+        "per_line": "^[0-9]+\\. [^[:space:]]+ — .+$"
+      },
+      "normalize": []
+    }
+  }
 }