@jenga-ai/agent 3.5.0 → 4.0.0

package/skills/jenga/playbooks/schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://jenga.local/schemas/jenga-playbook.schema.json",
   "title": "Jenga Multi-Skill Playbook",
-  "description": "Schema for a single multi-skill playbook definition consumed by skills/jenga/scripts/load-playbooks.sh (E53_S02_T01). A playbook is a dedicated, versionable data file describing an ORDERED chain of skills that /jenga's natural-language branch may propose (as an editable, confirmable numbered list -- see skills/jenga/scripts/render-playbook-confirmation.sh, E53_S02_T03) when free-text intent spans more than one skill and does not cleanly resolve to a single one via skills/route/SKILL.md's Step 2 matching. This file itself (schema.json) is never treated as a playbook -- load-playbooks.sh explicitly excludes it by filename when scanning skills/jenga/playbooks/*.json.",
+  "description": "Schema for a single multi-skill playbook definition consumed by skills/jenga/scripts/load-playbooks.sh (E53_S02_T01). A playbook is a dedicated, versionable data file describing an ORDERED chain of skills that /jenga's natural-language branch may propose (as an editable, confirmable numbered list -- see skills/jenga/scripts/render-playbook-confirmation.sh, E53_S02_T03) when free-text intent spans more than one skill and does not cleanly resolve to a single one via skills/jenga/SKILL.md's inlined Skill Matching & Invocation Contract. This file itself (schema.json) is never treated as a playbook -- load-playbooks.sh explicitly excludes it by filename when scanning skills/jenga/playbooks/*.json.",
   "type": "object",
   "required": ["id", "name", "description", "keywords", "examples", "steps"],
   "additionalProperties": false,
@@ -18,25 +18,92 @@
     },
     "description": {
       "type": "string",
-      "description": "One-sentence explanation of what this playbook accomplishes end-to-end, used as the lowest-priority match signal (description match, same as skills/route/SKILL.md's Step 2 Pass 3) when keywords/examples don't produce a confident match."
+      "description": "One-sentence explanation of what this playbook accomplishes end-to-end, used as the lowest-priority match signal (description match, same as skills/jenga/SKILL.md's inlined Skill Matching & Invocation Contract Pass 3) when keywords/examples don't produce a confident match."
     },
     "keywords": {
       "type": "array",
-      "description": "Short phrases (1-3 words) for verbatim, case-insensitive keyword matching against the raw natural-language prompt -- the highest-priority match signal (Pass 1), mirroring skills/route/SKILL.md's Step 2 Pass 1 semantics exactly, but scoped to this playbook's catalog rather than the single-skill catalog.",
+      "description": "Short phrases (1-3 words) for verbatim, case-insensitive keyword matching against the raw natural-language prompt -- the highest-priority match signal (Pass 1), mirroring skills/jenga/SKILL.md's inlined Skill Matching & Invocation Contract Pass 1 semantics exactly, but scoped to this playbook's catalog rather than the single-skill catalog.",
       "items": { "type": "string" },
       "minItems": 1
     },
     "examples": {
       "type": "array",
-      "description": "Natural-language example prompts a user might type that should resolve to this playbook. Used for the semantic similarity match (Pass 2), mirroring skills/route/SKILL.md's Step 2 Pass 2 semantics. At least one example must plausibly span the full breadth of this playbook's steps (not just its first step) so it is distinguishable from a plain single-skill match.",
+      "description": "Natural-language example prompts a user might type that should resolve to this playbook. Used for the semantic similarity match (Pass 2), mirroring skills/jenga/SKILL.md's inlined Skill Matching & Invocation Contract Pass 2 semantics. At least one example must plausibly span the full breadth of this playbook's steps (not just its first step) so it is distinguishable from a plain single-skill match.",
       "items": { "type": "string" },
       "minItems": 1
     },
     "steps": {
       "type": "array",
-      "description": "Ordered list of canonical skill DIRECTORY names (the directory under skills/<dir>/SKILL.md, e.g. \"j-brainstorm\", not the \"j.brainstorm\" frontmatter/invocation form and not the retired bare \"brainstorm\") that make up this playbook's chain, in the exact execution order. Per E50_S10's canonical naming contract the canonical directory is skills/j-<name>/, so a step value carries the j- prefix; the three permanent exceptions (jenga, jenga-permission-level, index) keep their bare directory names and are written bare. Each entry MUST resolve to an existing skills/<dir>/SKILL.md at load time -- load-playbooks.sh skips (with a stderr warning) any playbook referencing a nonexistent skill rather than silently including a broken chain in the catalog.",
-      "items": { "type": "string" },
+      "description": "Ordered list of steps making up this playbook's chain, in the exact execution order. A step is either a BARE STRING or a STEPOBJECT (E53_S03; composition added by E53_S05). A bare string is shorthand for {\"skill\": \"<name>\"} -- \"bare\" describes the JSON shape, never a bare skill NAME. A skill name is always a canonical skill DIRECTORY name (the directory under skills/<dir>/SKILL.md, e.g. \"j-brainstorm\", not the \"j.brainstorm\" frontmatter/invocation form and not the retired bare \"brainstorm\"); per E50_S10's canonical naming contract the canonical directory is skills/j-<name>/, so a step value carries the j- prefix, while the three permanent exceptions (jenga, jenga-permission-level, index) keep their bare directory names and are written bare. Each skill name MUST resolve to an existing skills/<dir>/SKILL.md at load time -- load-playbooks.sh skips (with a stderr warning) any playbook referencing a nonexistent skill rather than silently including a broken chain in the catalog. NOTE: this schema documents SHAPE only. The cross-step rules -- forward_from naming an EARLIER step whose skill declares a non-empty output_types, conditional.depends_on naming an EARLIER step, composition cycle/depth limits -- are not expressible here and are enforced by load-playbooks.sh, which remains the single source of truth for validation.",
+      "items": {
+        "oneOf": [
+          {
+            "type": "string",
+            "description": "Bare-string step: shorthand for {\"skill\": \"<name>\"}, unchanged original behavior. An all-bare-string playbook loads byte-for-byte the same as it did before E53_S03, and a bare-string step is never rewritten into object form in the loader's output."
+          },
+          { "$ref": "#/definitions/stepObject" }
+        ]
+      },
       "minItems": 2
     }
+  },
+  "definitions": {
+    "stepObject": {
+      "type": "object",
+      "description": "A StepObject step (E53_S03_T01). Carries EXACTLY ONE of the mutually exclusive target fields `skill` or `playbook` -- a step naming both, or naming neither, is rejected by load-playbooks.sh.",
+      "additionalProperties": false,
+      "oneOf": [
+        { "required": ["skill"], "not": { "required": ["playbook"] } },
+        { "required": ["playbook"], "not": { "required": ["skill"] } }
+      ],
+      "properties": {
+        "skill": {
+          "type": "string",
+          "description": "Invokes a single skill, same as a bare string. Value is a canonical skill directory name (see the `steps` description above)."
+        },
+        "playbook": {
+          "type": "string",
+          "description": "Composes another playbook by ID (E53_S05). Resolved and flattened in place at load time, so the emitted catalog's `steps` array never contains a raw playbook-type entry. Existence validation, cycle detection, and a configurable nesting-depth limit (project/configs/playbook-config.json's max_composition_depth, default 3) all apply."
+        },
+        "instruction": {
+          "type": "string",
+          "description": "Static natural-language text appended to this step's own invocation message."
+        },
+        "forward_from": {
+          "type": "string",
+          "description": "Names an EARLIER step in the same playbook (by that step's skill name) whose typed output becomes this step's actual invocation input. The named source's SKILL.md must declare a non-empty output_types -- a skill declaring nothing can never be a forward source. Transparent across composition boundaries, since composition resolution runs before this validation."
+        },
+        "resolve": {
+          "type": "string",
+          "description": "Natural-language instructions for reshaping/filtering/type-bridging the value forwarded into this step (e.g. \"pick the first three items\"). A step carrying both `resolve` and `playbook` is rejected at load time: resolve may never pre-authorize a downstream confirmation gate (E53_S07's safety review, permanently rejected)."
+        },
+        "conditional": {
+          "type": "object",
+          "description": "Runs this step only when the predicate holds against a named earlier step's captured output; otherwise the step is marked `skipped` and the chain continues without halting (E53_S04_T02). Unlike forward_from, this does NOT require the depended-on step to declare output_types.",
+          "additionalProperties": false,
+          "required": ["depends_on", "predicate"],
+          "properties": {
+            "depends_on": {
+              "type": "string",
+              "description": "Names an EARLIER skill step in this playbook whose captured output the predicate is evaluated against.",
+              "minLength": 1
+            },
+            "predicate": {
+              "type": "string",
+              "description": "The recognized predicate grammar, whose single source of truth is skills/jenga/scripts/run-playbook-step.sh: non_empty | empty | equals:<value> | not_equals:<value>.",
+              "pattern": "^(non_empty|empty|equals:.+|not_equals:.+)$"
+            }
+          }
+        },
+        "version": {
+          "type": "string",
+          "description": "RESERVED, currently a no-op. Accepted and passed through unchanged; not acted upon by anything yet. Exists so a future schema revision has a place to declare itself without a retroactive migration of every existing playbook."
+        },
+        "schema_version": {
+          "type": "string",
+          "description": "Alternate key name for `version`. Same reserved no-op semantics."
+        }
+      }
+    }
   }
 }

package/skills/jenga/playbooks/understand-then-commit.json

@@ -0,0 +1,19 @@
+{
+  "id": "understand-then-commit",
+  "name": "Understand Then Build",
+  "description": "Investigates existing or unfamiliar code first, then runs the full idea-to-commit pipeline on top of what was learned -- a composed chain built from the canonical idea-to-committed playbook, terminating at the commit.",
+  "keywords": [
+    "understand then build",
+    "investigate then build",
+    "explore then implement",
+    "onboard and build",
+    "learn the codebase first"
+  ],
+  "examples": [
+    "help me understand this codebase first, then plan a change here, build it, and commit it",
+    "investigate this existing code, then take an idea through planning, implementation, and a commit",
+    "look into what's already here, then brainstorm a fix, build it, and commit the work",
+    "onboard me to this project and then walk a new idea from planning through to a committed change"
+  ],
+  "steps": ["j-uncharted", {"playbook": "idea-to-committed"}]
+}

package/skills/jenga/scripts/load-nl-catalog.js

@@ -68,8 +68,11 @@ import { join } from "path";
 import { pathToFileURL } from "url";
 
 // The three permanent exceptions to the `j-<name>` canonical directory convention — see
-// docs/skill-authoring.md's Canonical Naming Contract and scripts/audit-twin-divergence.sh's
-// NEVER_TWINNED list, which this mirrors.
+// docs/skill-authoring.md's Canonical Naming Contract, and scripts/repoint-skill-refs.sh's
+// REPOINT_SKILL_REFS_EXCEPTIONS list, which this mirrors. (It previously mirrored the
+// twin-divergence audit script's NEVER_TWINNED tuple; that script was deleted when
+// E42_S07 retired the twin-parity gate, so both this comment and the cross-check in
+// tests/load-nl-catalog-twin-resolution.bats were repointed at the surviving list.)
 const NEVER_TWINNED = new Set(["jenga", "jenga-permission-level", "index"]);
 
 function canonicalSkillDir(name) {

package/skills/jenga/scripts/load-nl-catalog.sh

@@ -46,7 +46,7 @@ fi
 
 # Resolve the jenga-agent PACKAGE root (where lib/generate-skill-allow-list.js and the canonical
 # skills/ tree actually live) — same monorepo-checkout vs. installed-npm-package detection used
-# by skills/init/scripts/init.sh's PKG_ROOT resolution.
+# by skills/j-init/scripts/init.sh's PKG_ROOT resolution.
 if [ -d "$SCRIPT_DIR/../../../templates" ]; then
   PKG_ROOT="$SCRIPT_DIR/../../.."
 elif [ -d "$JENGA_PROJECT_DIR/node_modules/@jenga-ai/agent/templates" ]; then

package/skills/jenga/scripts/load-playbooks.sh

@@ -130,6 +130,84 @@
 #   anywhere in this loop. `conditional.depends_on` works identically, by the same mechanism.
 #
 # ---------------------------------------------------------------------------
+# TYPE REGISTRY (E62_S01_T04)
+# ---------------------------------------------------------------------------
+# The canonical type vocabulary this script validates against is `templates/playbook-types.json`
+# (E53_S03_T02, converted into a map of type descriptors by E62_S01_T01), resolved as
+# `<PKG_ROOT>/templates/playbook-types.json` — the SAME `PKG_ROOT` that already resolves
+# `PLAYBOOKS_DIR`/`SKILLS_DIR` above, so the `JENGA_PLAYBOOKS_TEST_ROOT` override (see "TESTING
+# OVERRIDE") redirects it too, and a fixture tree may supply its own vocabulary. The vocabulary is
+# ALWAYS read from that file's `types` map — this script never hardcodes a type name, and adding a
+# type to the registry is a data-only edit that requires no change here (see that file's own
+# `_comment`, "EXTENDING").
+#
+# Two load-time checks are driven from it. Both are about DECLARATIONS ONLY — what a SKILL.md
+# claims — never about an actual runtime VALUE. Verifying a value against its declared type is a
+# separate concern owned by `scripts/validate-typed-object.sh` (E62_S01_T02) and consumed at
+# runtime by `run-playbook-step.sh` (E62_S02); this script never calls it and never sees a value.
+#
+#   CHECK 1 — REGISTRY VOCABULARY. For EVERY skill named by a step in the final flattened step
+#   list (bare-string steps included, not only StepObjects, and not only `forward_from` sources),
+#   every type value the skill declares in its `output_types` or `input_types` frontmatter must be
+#   a key in the registry's `types` map. An unrecognized value (e.g. `output_types: banana`) skips
+#   the whole playbook with a stderr warning naming the offending value, the field it came from,
+#   and — for the `{when, type}` list form — the branch it came from. This check is INDEPENDENT of
+#   `forward_from`: it has repo-wide value on a playbook with no forward edges at all.
+#
+#   CHECK 2 — OUTPUT/INPUT COMPATIBILITY. Where a step declares `forward_from`, the SOURCE's
+#   declared `output_types` must be accepted by the CONSUMER's (i.e. this step's own skill's)
+#   declared `input_types`. This runs AFTER the existing declaredness and Blocker-1 structural
+#   checks above, so a source that declares nothing, or declares a malformed `{when, type}` entry,
+#   is still rejected by its own pre-existing message rather than by this one.
+#
+# THE ALL-BRANCHES RULE — both sides. Either side's declaration may be a single static type string
+# or a list of `{when, type}` branches. This check never needs to know which branch will actually
+# fire on either side, and never executes a classifier script to find out:
+#
+#   Compatible IFF every type the SOURCE could produce is accepted under EVERY CONSUMER branch.
+#   Equivalently: the set of source types must be a subset of the INTERSECTION of the consumer's
+#   accepted types.
+#
+# The source half of that rule (every source branch must produce a type the consumer accepts; any
+# branch that does not rejects the playbook, naming the offending branch) is the rule as originally
+# specified in E53. The CONSUMER half — what a conditional consumer, one whose own `input_types` is
+# a `{when, type}` list, means for compatibility — was left open by E62_S01_T03 and is RATIFIED
+# HERE (2026-09-19, E62_S01_T04) as the conservative dual stated above.
+#
+#   Rationale: which consumer branch applies at runtime is no more knowable at load time than which
+#   source branch applies. The only answer that is safe regardless of BOTH is the one that holds
+#   under both universally. It stays fully deterministic and executes no classifier script. No
+#   skill in this repository declares a conditional `input_types` today, so the ruling costs
+#   nothing now — it exists to close the ambiguity before it can bite.
+#
+#   Mechanically, each consumer branch accepts exactly one type, so the intersection is `{t}` when
+#   every branch declares the same `t`, and EMPTY when the branches disagree. An empty intersection
+#   rejects every forward into that consumer. That is the intended conservative outcome of the
+#   ruling, not an accident of the implementation.
+#
+# BACKWARD COMPATIBILITY — BINDING. A consumer that declares NO `input_types` at all retains
+# today's behavior EXACTLY: the forward is allowed on the existing source-declaredness check alone,
+# and Check 2 short-circuits before any comparison is made. The ABSENCE of a declaration is never a
+# violation. Adding the input side must not, and does not, retroactively break a single existing
+# playbook. (`docs/skill-authoring.md`'s `input_types` section states the same guarantee from the
+# skill author's side.)
+#
+# `text` IS NOT A WILDCARD. `text` carries `"verify": null` in the registry because prose has no
+# checkable shape, but it is a specific type in this compatibility lattice — never an `any`. It is
+# neither an `output_types` that satisfies every `input_types` nor an `input_types` that accepts
+# every `output_types`. Treating it as a universal acceptor would make every text-declaring skill
+# compatible with everything and render this check decorative, which is precisely what E53_S11's
+# honesty-over-breadth policy exists to prevent. Nothing in this script special-cases it.
+#
+# MISSING REGISTRY — DELIBERATE FAIL-OPEN. If the registry file is absent or unparseable, CHECK 1
+# is a silent no-op (no warning, no rejection); Check 2 is unaffected, since comparing declared
+# type NAMES needs no vocabulary. This matches this script's existing convention for an absent
+# optional input (a missing `project/.playbooks/` directory, a missing `playbook-config.json`), and
+# it is unreachable in a real invocation: PKG_ROOT detection is itself keyed on `templates/`
+# existing. It exists so a fixture tree under `JENGA_PLAYBOOKS_TEST_ROOT` may supply its own
+# registry, or deliberately supply none.
+#
+# ---------------------------------------------------------------------------
 # CONDITIONAL RESOLUTION (E53_S04_T02)
 # ---------------------------------------------------------------------------
 # A step's `conditional: {"depends_on": "<name>", "predicate": "<predicate>"}` is validated at load
@@ -418,6 +496,20 @@
 #   - A `conditional`'s `predicate` does not match the recognized grammar
 #     (`non_empty`/`empty`/`equals:<value>`/`not_equals:<value>`, defined
 #     in `run-playbook-step.sh`'s own header)                (E53_S04_T02) -> skipped
+#   - ANY step's skill declares an `output_types`/`input_types` value
+#     that is not a key in `templates/playbook-types.json`'s `types`
+#     map (Check 1)                                          (E62_S01_T04) -> skipped
+#     (applies to every skill-type step, bare string included -- not only
+#     `forward_from` sources; a silent no-op if the registry file itself is
+#     missing/unparseable, see "TYPE REGISTRY" above)
+#   - A `forward_from` source declares an `output_types` the consumer step's
+#     own `input_types` does not accept under EVERY consumer branch
+#     (Check 2, the all-branches rule)                       (E62_S01_T04) -> skipped
+#     (a consumer declaring NO `input_types` is never a violation -- the
+#     forward is allowed on the source-declaredness check alone, exactly as
+#     before this task)
+#   - A consumer's `input_types` list carries an entry missing `when`/`type`
+#                                                            (E62_S01_T04) -> skipped
 #
 # ---------------------------------------------------------------------------
 # EXIT CODES
@@ -474,7 +566,7 @@ else
 
   # Resolve the jenga-agent PACKAGE root (where the canonical skills/ tree actually lives) — same
   # monorepo-checkout vs. installed-npm-package detection used by
-  # skills/jenga/scripts/load-nl-catalog.sh's PKG_ROOT resolution and skills/init/scripts/init.sh.
+  # skills/jenga/scripts/load-nl-catalog.sh's PKG_ROOT resolution and skills/j-init/scripts/init.sh.
   if [ -d "$SCRIPT_DIR/../../../templates" ]; then
     PKG_ROOT="$SCRIPT_DIR/../../.."
     PROJECT_DIR="$JENGA_PROJECT_DIR"
@@ -515,6 +607,11 @@ project_dir = sys.argv[3] if len(sys.argv) > 3 and sys.argv[3] else None
 # --- E53_S06_T02: additive `lookup <id>` CLI mode --------------------------------------------
 mode = sys.argv[4] if len(sys.argv) > 4 and sys.argv[4] else "catalog"
 lookup_id = sys.argv[5] if len(sys.argv) > 5 else ""
+# --- E62_S01_T04: the jenga-agent PACKAGE root, where `templates/playbook-types.json` lives ---
+# Already resolved by the bash wrapper above (and already honoring JENGA_PLAYBOOKS_TEST_ROOT) --
+# threaded in here rather than re-derived, so there is exactly one PKG_ROOT resolution in this
+# script. See header "TYPE REGISTRY".
+pkg_root = sys.argv[6] if len(sys.argv) > 6 and sys.argv[6] else None
 
 # --- E53_S09_T01: project-local playbook source directory ------------------------------------
 # `project/.playbooks/`, resolved relative to the SAME project_dir already threaded above (which
@@ -568,6 +665,32 @@ def load_max_composition_depth(proj_dir):
 
 MAX_COMPOSITION_DEPTH = load_max_composition_depth(project_dir)
 
+
+# --- E62_S01_T04: the canonical type vocabulary -------------------------------------------------
+def load_type_registry(root):
+    """Read the set of known type names from `<root>/templates/playbook-types.json`'s `types` map.
+
+    Returns None when the registry is missing or unparseable, which makes the vocabulary check a
+    deliberate silent no-op -- see header 'TYPE REGISTRY' ("MISSING REGISTRY"). The vocabulary is
+    ALWAYS read from that file; no type name is ever hardcoded here, so adding a type to the
+    registry is a data-only edit requiring no change to this script.
+    """
+    if not root:
+        return None
+    registry_path = os.path.join(root, "templates", "playbook-types.json")
+    try:
+        with open(registry_path, encoding="utf-8") as fh:
+            registry = json.load(fh)
+    except (OSError, ValueError):
+        return None
+    types = registry.get("types") if isinstance(registry, dict) else None
+    if not isinstance(types, dict):
+        return None
+    return set(types.keys())
+
+
+TYPE_REGISTRY = load_type_registry(pkg_root)
+
 catalog = []
 # --- E53_S06_T02: per-basename skip-reason capture -------------------------------------------
 # Threaded through PASS 1, PASS 2 (resolve_playbook), and PASS 3 below -- whenever a playbook
@@ -662,8 +785,11 @@ def step_skill_name(step):
 _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.
+def extract_types_field(skill_md_path, field):
+    """Best-effort extraction of a type-declaration frontmatter field from a SKILL.md.
+
+    `field` is `output_types` or `input_types` (E62_S01_T04) -- both take the SAME two shapes (see
+    docs/skill-authoring.md), so they are read by this one parser rather than two copies of it.
 
     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. This is a small, targeted parser for
@@ -684,7 +810,7 @@ def extract_output_types(skill_md_path):
     fm_lines = fm_match.group(1).splitlines()
 
     for i, line in enumerate(fm_lines):
-        key_match = re.match(r'^output_types:\s*(.*)$', line)
+        key_match = re.match(r'^%s:\s*(.*)$' % re.escape(field), line)
         if not key_match:
             continue
 
@@ -727,6 +853,104 @@ def extract_output_types(skill_md_path):
     return None
 
 
+def extract_output_types(skill_md_path):
+    """The `output_types` half of extract_types_field -- kept as a named wrapper so every
+    pre-existing call site (E53_S03_T03/T04) reads exactly as it did before E62_S01_T04."""
+    return extract_types_field(skill_md_path, "output_types")
+
+
+def extract_input_types(skill_md_path):
+    """The `input_types` half of extract_types_field (E62_S01_T04)."""
+    return extract_types_field(skill_md_path, "input_types")
+
+
+# --- E62_S01_T04: shared normalization of either declaration shape ------------------------------
+def declared_type_entries(value):
+    """Normalize an `output_types`/`input_types` value into `[(type_or_None, when_or_None), ...]`.
+
+    A single static type string yields ONE entry whose `when` is None; a `{when, type}` list yields
+    one entry per branch. A malformed list entry (not an object, or missing `type`) yields a
+    `(None, when_or_None)` entry rather than being dropped, so a caller can tell "no branches" from
+    "a branch this function could not read". Both checks in header 'TYPE REGISTRY' consume this, so
+    neither re-derives the two shapes.
+    """
+    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 validate_declared_vocabulary(idx, skill_name, skill_md_path, registry):
+    """CHECK 1 -- every type value this skill declares must be a key in the registry's `types` map.
+
+    Returns an error string naming the offending value (and its branch, for the list form), or None.
+    A None `registry` never reaches here (the caller skips the check entirely -- see header
+    'TYPE REGISTRY', "MISSING REGISTRY").
+    """
+    known = ", ".join(sorted(registry)) if registry else "<none>"
+    for field in ("output_types", "input_types"):
+        declared = extract_types_field(skill_md_path, field)
+        for type_name, when_val in declared_type_entries(declared):
+            if type_name is None:
+                # A malformed `{when, type}` entry. Deliberately NOT this check's business: the
+                # pre-existing Blocker-1 structural check (E53_S03_T04) already owns that rejection
+                # for a forward source, with its own message.
+                continue
+            if type_name not in registry:
+                branch = " (branch when='%s')" % when_val if when_val else ""
+                return (
+                    f"step {idx} skill '{skill_name}' declares {field} '{type_name}'{branch}, "
+                    f"which is not a type in templates/playbook-types.json "
+                    f"(known types: {known})"
+                )
+    return None
+
+
+def accepted_input_types(value):
+    """The CONSUMER side of the all-branches rule (E62_S01_T04, ratified 2026-09-19).
+
+    Returns `(accepted_set_or_None, error_or_None)`:
+
+      - `(None, None)`  -- the consumer declares NO `input_types`. This is the BINDING backward-
+                           compatible case: the caller must allow the forward on the source-
+                           declaredness check alone, exactly as before this task. It is distinct
+                           from `(set(), None)` ("declares branches that agree on nothing"), and
+                           conflating the two would be precisely the retroactive break the task
+                           forbids.
+      - `(set, None)`   -- the set of types accepted under EVERY declared branch, i.e. the
+                           INTERSECTION. A single static type yields `{t}`. A `{when, type}` list
+                           yields `{t}` when every branch declares the same `t`, and an EMPTY set
+                           when they disagree -- an empty set rejects every forward, which is the
+                           intended conservative outcome of the ruling (see header 'TYPE REGISTRY').
+      - `(None, str)`   -- a malformed declaration; the string is the reason.
+    """
+    if not value:
+        return None, None
+    if isinstance(value, str):
+        return {value}, None
+    if not isinstance(value, list):
+        return None, "declares a malformed input_types (neither a type string nor a list)"
+
+    accepted = None
+    for item in value:
+        if not isinstance(item, dict) or not item.get("when") or not item.get("type"):
+            return None, "declares a malformed input_types entry (missing 'when' or 'type')"
+        branch_set = {item["type"]}
+        accepted = branch_set if accepted is None else (accepted & branch_set)
+    if accepted is None:
+        return None, "declares an empty input_types list"
+    return accepted, None
+
+
 try:
     builtin_filenames = sorted(
         f for f in os.listdir(playbooks_dir)
@@ -1014,7 +1238,26 @@ for pid in order:
         continue
 
     validation_error = None
+
+    # --- E62_S01_T04 CHECK 1: registry vocabulary validation (see header 'TYPE REGISTRY') -------
+    # Its own loop, deliberately separate from the forward_from/conditional loop below: that loop
+    # skips every non-dict step, and this check must cover BARE-STRING steps too -- it is keyed on
+    # the step's resolved skill name, not on the step carrying any particular field. A None
+    # registry (missing/unparseable file) makes the whole check a silent no-op.
+    if TYPE_REGISTRY is not None:
+        for idx, step in enumerate(flattened_steps):
+            step_name = step_skill_name(step)
+            if not step_name:
+                continue
+            validation_error = validate_declared_vocabulary(
+                idx, step_name, os.path.join(skills_dir, step_name, "SKILL.md"), TYPE_REGISTRY
+            )
+            if validation_error:
+                break
+
     for idx, step in enumerate(flattened_steps):
+        if validation_error:
+            break
         if not isinstance(step, dict):
             continue
 
@@ -1085,6 +1328,48 @@ for pid in order:
             if validation_error:
                 break
 
+        # --- E62_S01_T04 CHECK 2: output/input compatibility under the all-branches rule -------
+        # Runs AFTER the two checks above on purpose: a source that declares nothing, or declares
+        # a malformed {when, type} entry, is still rejected by its own pre-existing message, never
+        # by this one. See header 'TYPE REGISTRY'.
+        consumer_name = step_skill_name(step)
+        consumer_input_val = (
+            extract_input_types(os.path.join(skills_dir, consumer_name, "SKILL.md"))
+            if consumer_name
+            else None
+        )
+        accepted, accepted_error = accepted_input_types(consumer_input_val)
+        if accepted_error:
+            validation_error = f"step {idx} forward_from consumer '{consumer_name}' {accepted_error}"
+            break
+        if accepted is not None:
+            # `accepted is None` is the BINDING backward-compatible path: a consumer declaring no
+            # `input_types` is allowed on the source-declaredness check alone, exactly as before
+            # this task. Nothing below runs for it.
+            offending = next(
+                (
+                    (type_val, when_val)
+                    for type_val, when_val in declared_type_entries(output_types_val)
+                    if type_val is not None and type_val not in accepted
+                ),
+                None,
+            )
+            if offending:
+                offending_type, offending_when = offending
+                branch_desc = (
+                    f"output_types branch when='{offending_when}'"
+                    if offending_when
+                    else "static output_types"
+                )
+                accepted_desc = ", ".join(sorted(accepted)) if accepted else "<none>"
+                validation_error = (
+                    f"step {idx} 'forward_from' source '{source_name}' {branch_desc} produces "
+                    f"type '{offending_type}', which consumer '{consumer_name}' does not accept "
+                    f"under every input_types branch (accepted under all branches: "
+                    f"{accepted_desc})"
+                )
+                break
+
     if validation_error:
         print(f"Warning: {path} {validation_error} — skipped", file=sys.stderr)
         skip_reasons[pid] = validation_error
@@ -1129,5 +1414,5 @@ if mode == "lookup":
 print(json.dumps(catalog, indent=2))
 PY
 
-python3 "$PY_SCRIPT" "$PLAYBOOKS_DIR" "$SKILLS_DIR" "$PROJECT_DIR" "$MODE" "$LOOKUP_ID"
+python3 "$PY_SCRIPT" "$PLAYBOOKS_DIR" "$SKILLS_DIR" "$PROJECT_DIR" "$MODE" "$LOOKUP_ID" "$PKG_ROOT"
 exit $?

package/skills/jenga/scripts/match-playbook.sh

@@ -3,10 +3,10 @@
 # skills/jenga/scripts/match-playbook.sh
 #
 # Deterministic PLAYBOOK matcher for `/jenga`'s natural-language branch (E53_S02_T02). Runs the
-# same three-pass matching *philosophy* as `skills/route/SKILL.md`'s Step 2 (keyword ->
-# example similarity -> description), but scoped to the playbook catalog produced by
-# `load-playbooks.sh` (E53_S02_T01) instead of the single-skill catalog `load-nl-catalog.sh`
-# produces for `/route`/`/jenga`'s existing single-skill matching.
+# same three-pass matching *philosophy* as `skills/jenga/SKILL.md`'s inlined Skill Matching &
+# Invocation Contract (keyword -> example similarity -> description), but scoped to the playbook
+# catalog produced by `load-playbooks.sh` (E53_S02_T01) instead of the single-skill catalog
+# `load-nl-catalog.sh` produces for `/route`/`/jenga`'s existing single-skill matching.
 #
 # ---------------------------------------------------------------------------
 # THIS IS A FALLBACK — READ BEFORE WIRING (E53_S02_T04)