@jenga-ai/agent 3.2.0 → 3.5.0

package/skills/j-playbook-new/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: j.playbook-new
+description: Guided wizard that walks you through authoring a new project-local playbook — id, name, description, keywords, examples, and an ordered list of skills — validates every input against the real catalogs, and self-validates the written file before reporting success.
+keywords:
+  - new playbook
+  - create playbook
+  - author playbook
+  - project playbook
+  - custom playbook
+examples:
+  - "I want to create my own playbook"
+  - "help me author a new project-local playbook"
+  - "set up a custom workflow chain for my project"
+  - "j.playbook-new"
+---
+
+# Playbook New — Guided Playbook-Authoring Wizard
+
+## Purpose
+
+`skills/jenga/scripts/load-playbooks.sh` merges two playbook sources into one catalog: the
+framework-owned `skills/jenga/playbooks/` tree, and a project-owned `project/.playbooks/`
+directory (`E53_S09_T01`). This skill is the guided authoring path for the second source — it
+walks the user step by step through the required fields, validates each one against the real,
+live catalogs (never a hand-maintained list of skill names or existing playbook ids), writes
+`project/.playbooks/<id>.json`, and re-validates the just-written file via
+`skills/jenga/scripts/load-playbooks.sh lookup` before ever declaring success. Hand-editing the
+written JSON file remains the escape hatch for anything this wizard doesn't author (see the "v1
+scope cut" note below).
+
+**All deterministic work — slug/uniqueness validation, catalog lookups, and the JSON write
+itself — lives in `skills/j-playbook-new/scripts/playbook-new.sh`** (per `CLAUDE.md`'s "Scripts
+Over Inline Logic" principle). This skill's own job is only to run the conversational loop around
+that script and interpret its JSON results — it never re-implements any validation or catalog
+logic inline.
+
+**v1 scope cut (deliberate, matches `E53_S09`'s story-level scope cut):** this wizard authors
+plain, ordered, bare-string skill-name chains only — no `forward_from`, `resolve`, `conditional`,
+or `playbook`-type (composition) `StepObject` fields. Hand-edit the written file directly if you
+need any of those.
+
+**Scope note — keywords and examples.** The playbook schema
+(`skills/jenga/playbooks/schema.json`) requires every playbook to carry non-empty `keywords` and
+`examples` arrays, exactly like every existing built-in playbook file already does — these are
+what let `/jenga`'s own natural-language matching (`match-playbook.sh`) ever propose this playbook
+from a free-text request. This wizard therefore asks for both, in addition to id/name/description/
+skill-list, so the result is a genuinely useful, matchable playbook rather than one that merely
+parses.
+
+## Instructions
+
+1. **Ask for an id** — a short, stable, kebab-case identifier (e.g. `my-release-flow`). Validate
+   it by running:
+   ```
+   skills/j-playbook-new/scripts/playbook-new.sh validate-id "<id>"
+   ```
+   Parse the single JSON object printed to stdout:
+   - `{"valid": true}` — continue to step 2.
+   - `{"valid": false, "reason": "..."}` — show the `reason` to the user verbatim and re-prompt
+     for a different id. Do not proceed until a validation call returns `valid: true`.
+
+2. **Ask for a `name`** — a short, human-readable display name (e.g. "My Release Flow"), shown to
+   users in confirmation prompts and routing output, mirroring every existing playbook's `name`
+   field. No script validation needed beyond "non-empty" — re-prompt if the user gives an empty
+   answer.
+
+3. **Ask for a `description`** — one sentence explaining what this playbook accomplishes
+   end-to-end. Re-prompt if empty.
+
+4. **Ask for `keywords`** — one or more short phrases (1-3 words each) a user might type that
+   should match this playbook, mirroring every existing playbook's `keywords` field (see
+   `skills/jenga/playbooks/brainstorm-to-mirror.json` for a concrete example of the expected
+   shape and specificity). Accept them one at a time or as a single comma-separated batch —
+   your judgment, whichever the user's response shape suggests. Require at least one.
+
+5. **Ask for `examples`** — one or more natural-language example prompts a user might type that
+   should resolve to this playbook (again, mirror the existing built-in playbooks' style and
+   level of specificity). Require at least one; at least one example should plausibly span the
+   full breadth of the playbook's steps, not just its first one, so it's distinguishable from a
+   single-skill match — use your judgment coaching the user toward this if their first example is
+   too narrow.
+
+6. **Ask for an ordered list of skill names** — one at a time, or as a single ordered batch —
+   your judgment based on how the user responds. For **each** name entered, validate it by
+   running:
+   ```
+   skills/j-playbook-new/scripts/playbook-new.sh validate-skill "<name>"
+   ```
+   Parse the JSON result:
+   - `{"valid": true}` — accept it into the ordered list and continue.
+   - `{"valid": false, "reason": "..."}` — show the `reason` verbatim and re-prompt for that
+     position in the list (do not silently drop it or guess a correction).
+
+   Once the user signals they're done adding skills, require **at least 2** total (a playbook is a
+   chain — a single-skill "playbook" isn't a meaningful use of this mechanism). If fewer than 2
+   were entered, tell the user this and continue prompting for more.
+
+7. **Write the playbook.** Assemble the JSON payload from steps 1-6:
+   ```json
+   {
+     "id": "<id>",
+     "name": "<name>",
+     "description": "<description>",
+     "keywords": ["<keyword 1>", "..."],
+     "examples": ["<example 1>", "..."],
+     "steps": ["<skill 1>", "<skill 2>", "..."]
+   }
+   ```
+   Pipe it to stdin of:
+   ```
+   skills/j-playbook-new/scripts/playbook-new.sh write
+   ```
+   Parse the JSON result:
+   - `{"written": true, "path": "..."}` — continue to step 8.
+   - `{"written": false, "reason": "..."}` — show the `reason` to the user verbatim. This should
+     only happen if something changed between validation and write (e.g. a race, or a shape
+     issue this wizard's own prompts didn't already catch) — do not silently retry; tell the user
+     what failed and, if it's fixable (e.g. the id collided after all), loop back to the relevant
+     earlier step.
+
+8. **Self-validate before declaring success — never skip this step.** Run:
+   ```
+   skills/jenga/scripts/load-playbooks.sh lookup "<id>"
+   ```
+   Branch on the returned `status`:
+   - **`"valid"`** — report success to the user: the playbook was written to
+     `project/.playbooks/<id>.json` and is confirmed loadable. Mention it can now be invoked via
+     `j.playbook <id>` or matched naturally through `j.jenga`.
+   - **`"invalid"`** — report the `reason` field to the user **verbatim** — never a generic
+     failure message. This is a real defect (the write succeeded but load-time validation still
+     rejects it) — do not claim success.
+   - **`"not_found"`** — report to the user that the write appears to have silently failed (the
+     file the wizard just wrote could not be found by the loader) — this would indicate an
+     environment problem (e.g. a different project root being resolved by the two scripts), not a
+     normal outcome. Never claim success.
+
+   Under no circumstances report success to the user without having seen `"status": "valid"` from
+   this exact call.
+
+## Edge Cases
+
+- **The user wants to add `forward_from`/`resolve`/`conditional`/composition to a step.** Tell
+  them this wizard doesn't author those fields (v1 scope cut) and that they can hand-edit
+  `project/.playbooks/<id>.json` afterward — the schema supports these fields identically
+  regardless of which directory a playbook file lives in.
+- **The id collides with a project playbook that already exists on disk but is currently
+  invalid** (e.g. a hand-edited file with a JSON syntax error) — `validate-id` still rejects it (it
+  checks raw file existence, not just catalog membership) rather than silently overwriting a file
+  the user may not realize is broken.
+- **A skill name the user enters exists under multiple forms in the catalog** (e.g. both a bare
+  and a `j-`-prefixed directory, during this repo's ongoing `E50` naming-contract transition) —
+  accept whichever exact form the user typed if `validate-skill` reports it valid; this wizard
+  does not impose a preference between forms the catalog itself doesn't distinguish.
+- **The user cancels mid-wizard** — do not write anything; only step 7 ever touches disk, and only
+  once a complete, locally-validated payload exists.

package/skills/j-playbook-new/scripts/playbook-new.sh

@@ -0,0 +1,332 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# skills/j-playbook-new/scripts/playbook-new.sh
+#
+# Deterministic helper behind the `j.playbook-new` guided wizard (E53_S09_T02). Per CLAUDE.md's
+# "Scripts Over Inline Logic" principle, every mechanical step of the wizard -- id slug/uniqueness
+# validation, skill-name validation against the real catalog, and the JSON write itself -- lives
+# here rather than as inline agent prose in skills/j-playbook-new/SKILL.md. The agent driving the
+# wizard calls this script once per step and interprets its JSON result; it never re-implements
+# any of this logic itself.
+#
+# Reuses, never re-implements, the two existing single-source-of-truth catalogs:
+#   - skills/jenga/scripts/load-playbooks.sh   (merged builtin+project playbook catalog, E53_S09_T01)
+#   - skills/jenga/scripts/load-nl-catalog.sh  (the real, generated skill catalog /jenga's own
+#                                                natural-language matching already uses)
+#
+# ---------------------------------------------------------------------------
+# USAGE
+# ---------------------------------------------------------------------------
+#   playbook-new.sh validate-id <id>
+#
+# Checks <id> is slug-safe (the same pattern skills/jenga/playbooks/schema.json requires:
+# ^[a-z0-9]+(-[a-z0-9]+)*$) and does not collide with any id already present in the merged catalog
+# (skills/jenga/scripts/load-playbooks.sh, no arguments -- built-in and project sources both) OR an
+# existing (possibly currently invalid, and therefore catalog-invisible) file at
+# project/.playbooks/<id>.json. Prints exactly one JSON object to stdout:
+#   {"valid": true}
+#   {"valid": false, "reason": "<human-readable reason>"}
+# Exit 0 for BOTH outcomes -- mirrors load-playbooks.sh's own `lookup` mode convention of
+# reserving a non-zero exit for usage/setup errors only, never for a normal negative validation
+# result the caller is expected to branch on.
+#
+#   playbook-new.sh validate-skill <name>
+#
+# Checks <name> is a real, currently-loadable skill per skills/jenga/scripts/load-nl-catalog.sh's
+# generated catalog -- the exact source /jenga's own natural-language matching already uses, never
+# a hand-maintained list. Prints:
+#   {"valid": true}
+#   {"valid": false, "reason": "..."}
+# Exit 0 for both outcomes, same convention as validate-id.
+#
+#   playbook-new.sh write
+#
+# Reads a single JSON object from stdin:
+#   {"id": "...", "name": "...", "description": "...", "keywords": ["..."],
+#    "examples": ["..."], "steps": ["...", "..."]}
+# Pre-validates it against the same required-field / non-empty-list / steps-shape rules
+# skills/jenga/playbooks/schema.json declares (id slug pattern, all six required fields present,
+# keywords/examples non-empty lists of non-empty strings, steps a list of >= 2 non-empty strings --
+# this wizard authors bare-string steps only, per this task's v1 scope cut) BEFORE writing anything
+# to disk. This is a defensive, redundant pre-check only -- the actual source of truth for validity
+# remains load-playbooks.sh's own load-time validation, which the wizard's own self-validation step
+# (SKILL.md step 8) always runs afterward regardless of this result. Creates project/.playbooks/ if
+# it does not yet exist, and refuses to overwrite an already-existing file for the same id. On
+# success, writes project/.playbooks/<id>.json (pretty-printed) and prints
+# {"written": true, "path": "<absolute path>"}. On any shape/overwrite failure, prints
+# {"written": false, "reason": "..."} and writes nothing. Exit 0 for both outcomes.
+#
+# ---------------------------------------------------------------------------
+# PROJECT ROOT RESOLUTION
+# ---------------------------------------------------------------------------
+# Honors JENGA_PLAYBOOKS_TEST_ROOT -- the SAME override variable load-playbooks.sh itself defines
+# (see that script's header "TESTING OVERRIDE"), not a second, script-specific one -- so a fixture
+# pointing this script at a throwaway project root also makes load-playbooks.sh (invoked internally
+# by validate-id, and by the wizard's own later self-validation step) resolve project/.playbooks/
+# under that same root. Never set this variable in a real invocation.
+#
+# ---------------------------------------------------------------------------
+# EXIT CODES
+# ---------------------------------------------------------------------------
+#   0   a result JSON object was printed to stdout (whether valid:true/false or written:true/false)
+#   2   usage error, or a real setup failure (missing python3, the sibling load-playbooks.sh /
+#       load-nl-catalog.sh scripts could not be located, one of them exited non-zero, or the
+#       project/.playbooks/ directory could not be created)
+#
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LOAD_PLAYBOOKS="$SCRIPT_DIR/../../jenga/scripts/load-playbooks.sh"
+LOAD_NL_CATALOG="$SCRIPT_DIR/../../jenga/scripts/load-nl-catalog.sh"
+
+if [ ! -f "$LOAD_PLAYBOOKS" ]; then
+  echo "Error: could not locate load-playbooks.sh at $LOAD_PLAYBOOKS" >&2
+  exit 2
+fi
+if [ ! -f "$LOAD_NL_CATALOG" ]; then
+  echo "Error: could not locate load-nl-catalog.sh at $LOAD_NL_CATALOG" >&2
+  exit 2
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "Error: python3 is required by playbook-new.sh" >&2
+  exit 2
+fi
+
+if [ -n "${JENGA_PLAYBOOKS_TEST_ROOT:-}" ]; then
+  # Test-only override -- see header "PROJECT ROOT RESOLUTION" above. Never set in a real
+  # invocation.
+  PROJECT_DIR="$JENGA_PLAYBOOKS_TEST_ROOT"
+else
+  PROJECT_DIR="${JENGA_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || pwd)}}"
+fi
+PLAYBOOKS_TARGET_DIR="$PROJECT_DIR/project/.playbooks"
+
+if [ $# -lt 1 ]; then
+  echo "Usage: $(basename "$0") <validate-id|validate-skill|write> [args...]" >&2
+  exit 2
+fi
+MODE="$1"
+shift
+
+PY_SCRIPT="$(mktemp -t playbook-new-XXXXXX.py)"
+trap 'rm -f "$PY_SCRIPT"' EXIT
+
+cat > "$PY_SCRIPT" <<'PY'
+import json
+import os
+import re
+import sys
+
+mode = sys.argv[1]
+SLUG_RE = re.compile(r'^[a-z0-9]+(-[a-z0-9]+)*$')
+
+
+def emit(obj):
+    print(json.dumps(obj))
+
+
+if mode == "validate-id":
+    target_id = sys.argv[2]
+    playbooks_target_dir = sys.argv[3]
+
+    if not SLUG_RE.match(target_id):
+        emit({
+            "valid": False,
+            "reason": (
+                f"'{target_id}' is not slug-safe -- must match ^[a-z0-9]+(-[a-z0-9]+)*$ "
+                f"(lowercase letters, digits, single hyphens between segments)"
+            ),
+        })
+        sys.exit(0)
+
+    existing_file = os.path.join(playbooks_target_dir, f"{target_id}.json")
+    if os.path.isfile(existing_file):
+        emit({
+            "valid": False,
+            "reason": (
+                f"a file already exists at {existing_file} -- choose a different id or edit "
+                f"that file directly"
+            ),
+        })
+        sys.exit(0)
+
+    try:
+        catalog = json.load(sys.stdin)
+    except Exception as e:
+        emit({
+            "valid": False,
+            "reason": f"could not read the playbook catalog to check for collisions ({e})",
+        })
+        sys.exit(0)
+
+    for entry in catalog:
+        if entry.get("id") == target_id:
+            src = entry.get("source", "unknown")
+            emit({
+                "valid": False,
+                "reason": (
+                    f"id '{target_id}' collides with an already-loaded {src} playbook (see "
+                    f"skills/jenga/scripts/load-playbooks.sh's merged catalog) -- choose a "
+                    f"different id"
+                ),
+            })
+            sys.exit(0)
+
+    emit({"valid": True})
+    sys.exit(0)
+
+elif mode == "validate-skill":
+    target_name = sys.argv[2]
+
+    try:
+        nl_catalog = json.load(sys.stdin)
+    except Exception as e:
+        emit({"valid": False, "reason": f"could not read the generated skill catalog ({e})"})
+        sys.exit(0)
+
+    for entry in nl_catalog:
+        if entry.get("name") == target_name:
+            emit({"valid": True})
+            sys.exit(0)
+
+    emit({
+        "valid": False,
+        "reason": (
+            f"'{target_name}' is not a recognized skill directory name in the generated skill "
+            f"catalog (skills/jenga/scripts/load-nl-catalog.sh) -- check spelling and the exact "
+            f"directory-name form the catalog currently lists"
+        ),
+    })
+    sys.exit(0)
+
+elif mode == "write":
+    playbooks_target_dir = sys.argv[2]
+
+    try:
+        payload = json.load(sys.stdin)
+    except Exception as e:
+        emit({"written": False, "reason": f"stdin was not valid JSON ({e})"})
+        sys.exit(0)
+
+    if not isinstance(payload, dict):
+        emit({"written": False, "reason": "stdin JSON must be an object"})
+        sys.exit(0)
+
+    required_fields = ["id", "name", "description", "keywords", "examples", "steps"]
+    missing = [f for f in required_fields if f not in payload]
+    if missing:
+        emit({"written": False, "reason": f"missing required field(s) {missing}"})
+        sys.exit(0)
+
+    target_id = payload["id"]
+    if not isinstance(target_id, str) or not SLUG_RE.match(target_id):
+        emit({
+            "written": False,
+            "reason": f"id '{target_id}' is not slug-safe -- must match ^[a-z0-9]+(-[a-z0-9]+)*$",
+        })
+        sys.exit(0)
+
+    for field in ("name", "description"):
+        if not isinstance(payload[field], str) or not payload[field]:
+            emit({"written": False, "reason": f"'{field}' must be a non-empty string"})
+            sys.exit(0)
+
+    for field in ("keywords", "examples"):
+        value = payload[field]
+        if (
+            not isinstance(value, list)
+            or len(value) == 0
+            or not all(isinstance(v, str) and v for v in value)
+        ):
+            emit({
+                "written": False,
+                "reason": f"'{field}' must be a non-empty list of non-empty strings",
+            })
+            sys.exit(0)
+
+    steps = payload["steps"]
+    if not isinstance(steps, list) or len(steps) < 2 or not all(isinstance(s, str) and s for s in steps):
+        emit({
+            "written": False,
+            "reason": (
+                "'steps' must be a list of at least 2 non-empty strings (bare skill-name steps "
+                "only -- this wizard authors no StepObject fields, per this task's v1 scope cut)"
+            ),
+        })
+        sys.exit(0)
+
+    target_file = os.path.join(playbooks_target_dir, f"{target_id}.json")
+    if os.path.isfile(target_file):
+        emit({
+            "written": False,
+            "reason": f"a file already exists at {target_file} -- refusing to overwrite",
+        })
+        sys.exit(0)
+
+    try:
+        os.makedirs(playbooks_target_dir, exist_ok=True)
+    except OSError as e:
+        print(f"Error: could not create {playbooks_target_dir}: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    ordered = {
+        "id": target_id,
+        "name": payload["name"],
+        "description": payload["description"],
+        "keywords": payload["keywords"],
+        "examples": payload["examples"],
+        "steps": steps,
+    }
+
+    try:
+        with open(target_file, "w", encoding="utf-8") as fh:
+            json.dump(ordered, fh, indent=2)
+            fh.write("\n")
+    except OSError as e:
+        print(f"Error: could not write {target_file}: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    emit({"written": True, "path": os.path.abspath(target_file)})
+    sys.exit(0)
+
+else:
+    print(f"Error: unrecognized mode '{mode}' (usage: validate-id|validate-skill|write)", file=sys.stderr)
+    sys.exit(2)
+PY
+
+case "$MODE" in
+  validate-id)
+    if [ $# -lt 1 ] || [ -z "${1:-}" ]; then
+      echo "Usage: $(basename "$0") validate-id <id>" >&2
+      exit 2
+    fi
+    TARGET_ID="$1"
+    if ! CATALOG_JSON="$("$LOAD_PLAYBOOKS")"; then
+      echo "Error: load-playbooks.sh failed while checking id '$TARGET_ID' for collisions" >&2
+      exit 2
+    fi
+    printf '%s' "$CATALOG_JSON" | python3 "$PY_SCRIPT" validate-id "$TARGET_ID" "$PLAYBOOKS_TARGET_DIR"
+    ;;
+  validate-skill)
+    if [ $# -lt 1 ] || [ -z "${1:-}" ]; then
+      echo "Usage: $(basename "$0") validate-skill <name>" >&2
+      exit 2
+    fi
+    TARGET_NAME="$1"
+    if ! NL_CATALOG_JSON="$("$LOAD_NL_CATALOG")"; then
+      echo "Error: load-nl-catalog.sh failed while validating skill name '$TARGET_NAME'" >&2
+      exit 2
+    fi
+    printf '%s' "$NL_CATALOG_JSON" | python3 "$PY_SCRIPT" validate-skill "$TARGET_NAME"
+    ;;
+  write)
+    python3 "$PY_SCRIPT" write "$PLAYBOOKS_TARGET_DIR"
+    ;;
+  *)
+    echo "Error: unrecognized mode '$MODE' (usage: $(basename "$0") <validate-id|validate-skill|write> [args...])" >&2
+    exit 2
+    ;;
+esac

package/skills/j-publish/scripts/npm_ci_pipeline.sh

@@ -191,6 +191,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Install project/app workspace dependencies (E29_S05_T01)
+        run: npm ci --prefix project/app
+
       - name: Regenerate lib/legacy-shipped-paths.json (E26_S08_T03)
         run: node scripts/generate-legacy-shipped-paths.js || echo "::warning::legacy-shipped-paths generation failed; publishing without an updated list"
 
@@ -224,6 +227,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Install project/app workspace dependencies (E29_S05_T01)
+        run: npm ci --prefix project/app
+
       - name: Stage to npm
         run: npm stage publish --provenance --access ${NPM_ACCESS} --tag ${DIST_TAG}
 

package/skills/j-skillify/assets/init-new/assets/.gitignore_template

@@ -11,5 +11,4 @@ Desktop.ini
 # Dependency directories
 node_modules/
 vendor/
-.venv/
-EOF
+.venv/

package/skills/j-uncharted/SKILL.md

@@ -168,6 +168,7 @@ For genuinely undocumented code, there is often no reliable human oracle to conf
 
 - **The deterministic pipeline remains the tool of record for zero-oracle codebases.** `onboard --legacy` and `segment --mode delivery` never depend on anyone confirming intent — they ground everything in mechanical evidence (file structure, dependencies, test coverage) and say so explicitly under `Open Questions` when the evidence doesn't support a conclusion. When there is no one left who understands the code, reach for one of those, not the conversational flow.
 - **When running the conversational flow, do not manufacture confidence.** If the user's answer is uncertain, hedged, or contradicts what discovery/Investigative Mode found, write the node honestly — do not round an uncertain answer up to a confirmed one. There is no schema field yet to tag confidence (the stub schema is intentionally minimal); until one exists, say so in the node's `description` text itself (e.g. "per the user, this module retries failed charges — unconfirmed against the code, which shows only a single retry attempt") rather than silently dropping the caveat.
+- **`verification_depth: strict` is this guidance's concrete implementation, not a separate idea (E40_S06_T02).** When a candidate's Familiarity Check answer is `No` (Convergence Loop Step 1), Step 4's risk-weighted gating never lets an escalating finding round up to a false confirmation by asking the user to bless it — it auto-flags the node with exactly the hedged-`description` convention this bullet describes and converges it without a prompt. This bullet states the principle; Step 4's `strict` branch is what enforces it mechanically, so the two sections should be read as one mechanism, not two independently-arrived-at claims.
 - **A confidently wrong answer is not detectable by this flow.** Corroboration against a second signal (commit history, existing docs, a second person) is the only mitigation, and it is not built here — this is the accepted residual risk, not a gap to engineer around mid-conversation.
 
 ### Directory Triage
@@ -213,10 +214,56 @@ Silence, a counter-question, or an ambiguous reply is not consent — re-ask, th
 
 Runs once per surviving candidate (a subsystem, a named flow, a directory) after Directory Triage. This is the "propose understanding, ask the user to confirm or correct" cycle at the center of the redesign — and the one the scrutiny flagged as having no termination bound and no defense against confirmation fatigue. Both gaps are closed mechanically, not by agent discipline alone:
 
-1. **Dispatch Investigative Mode.** Per `agents/developer.md`'s and `agents/tester.md`'s Investigative Mode sections (E20_S08_T02), dispatch the developer to trace what the code actually does for the candidate, and the tester to trace what the test suite actually exercises and verifies for the same candidate — two distinct vantage points, not two names for the same read. Both are read-only, worktree-sandboxed, no commits, no board writes.
-2. **Propose understanding.** From both traces, draft the candidate's coarse graph node(s)/edge(s) (per the stub schema) and a plain-language summary of what they represent.
-3. **Risk-weighted gating — not every finding gets a prompt.** This is the fix for confirmation fatigue (solution assessment, Problem 6, Solution B — RECOMMENDED): force an explicit confirmation only for **high-uncertainty or high-impact** findings — a node whose description depends on an inference the traces don't fully support, a node with many outgoing edges (structurally central), or one the Human-Oracle-Availability Limitation above already flagged as uncertain. **Auto-accept** low-risk, high-confidence findings — the traces agree, the finding is narrow in scope, nothing about it is surprising — without a prompt, but **log every auto-accepted node** in the elicitation state's checkpoint data (see below) so the decision is auditable later, per that solution's own mitigation for "the scoring mechanism itself misjudges impact."
-4. **Confirm/correct, one round per call to `elicitation-state.sh turn`.** For a node requiring confirmation, present the draft and ask the user to confirm or correct it (per the Interaction Pattern in `CLAUDE.md` — confirm / correct-with-detail / defer as "unconfirmed" / other). Each round, call:
+1. **Familiarity Check — once per candidate, before Investigative Mode dispatch.** Ask (per the Interaction Pattern in `CLAUDE.md` — numbered list, free-text last):
+
+   ```
+   Are you familiar with this service/segment?
+   1. Yes
+   2. A little
+   3. No
+   4. Other (describe below)
+   ```
+
+   Silence, a counter-question, or an ambiguous reply is not consent — re-ask, the same convention used at every other confirmation gate in this skill. Map the answer to a `verification_depth` scoped to this candidate only — `Yes` → `shallow`, `A little` → `moderate`, `No` → `strict` — and persist it immediately, keyed by this candidate's node id, via `elicitation-state.sh`'s checkpoint mechanism (see Multi-Session Persistence below for the exact call and merge semantics):
+
+   ```bash
+   printf '{"verification_depth": {"%s": "%s"}}' "<candidate-id>" "<shallow|moderate|strict>" \
+     | bash skills/j-uncharted/scripts/elicitation-state.sh checkpoint --id <elicitation-id> --json -
+   ```
+
+   **Check before asking.** A candidate whose `verification_depth` is already present in the state file's `checkpoint.verification_depth` (per Multi-Session Persistence below) has already answered this — do not re-ask it, on a fresh session or otherwise.
+
+   This question operationalizes the Human-Oracle-Availability Limitation above — it is the mechanism for finding out, per candidate, how much weight the user's own confirmations should carry, rather than assuming a uniform level of trust for every candidate in one run. **`verification_depth` is read back and consumed by Step 4's risk-weighted gating below (`E40_S06_T02`)**, which branches its auto-accept/confirm/auto-flag behavior per depth. The fixed internal/external question template used whenever shallow/moderate gating does decide to prompt (Step 5) is `skills/j-uncharted/assets/NODE_QUESTION_TEMPLATE.md` (`E40_S06_T03`) — this step's job remains asking the question and making the answer durable for those steps to read.
+2. **Dispatch Investigative Mode.** Per `agents/developer.md`'s and `agents/tester.md`'s Investigative Mode sections (E20_S08_T02), dispatch the developer to trace what the code actually does for the candidate, and the tester to trace what the test suite actually exercises and verifies for the same candidate — two distinct vantage points, not two names for the same read. Both are read-only, worktree-sandboxed, no commits, no board writes.
+3. **Propose understanding.** From both traces, draft the candidate's coarse graph node(s)/edge(s) (per the stub schema) and a plain-language summary of what they represent.
+4. **Risk-weighted gating — not every finding gets a prompt, and `verification_depth` (Step 1) decides how gating itself behaves, not just what counts as risky.** This is the fix for confirmation fatigue (solution assessment, Problem 6, Solution B — RECOMMENDED). The baseline escalation criteria — the three triggers that force an explicit confirmation — are unchanged from before `E40_S06`:
+
+   - **T1 — inference-dependent:** the node's description depends on an inference the traces don't fully support.
+   - **T2 — structurally central:** the node has many outgoing edges.
+   - **T3 — already-flagged uncertain:** the Human-Oracle-Availability Limitation above already flagged this finding as uncertain.
+
+   A finding tripping none of T1-T3 is **low-risk** and auto-accepts regardless of depth. A finding tripping any of T1-T3 is **escalating**, and what happens to it now branches on the current candidate's `verification_depth` (read from `checkpoint.verification_depth.<candidate-id>`, per Step 1):
+
+   - **`moderate` (the default, unchanged calibration)** — exactly today's behavior: every escalating finding (any of T1-T3) forces a confirm prompt (Step 5); every low-risk finding auto-accepts without a prompt. **Log every auto-accepted node** in the elicitation state's checkpoint data (see Multi-Session Persistence below) so the decision is auditable later, per that solution's own mitigation for "the scoring mechanism itself misjudges impact."
+   - **`shallow` (widened auto-accept)** — the concrete widening rule: **drop T2 (structurally central) as an escalation trigger.** A finding tripping T2 alone — structurally central, but not inference-dependent and not already flagged uncertain — is reclassified low-risk and auto-accepted (still logged, same as above) instead of escalating. T1 and T3 still force a confirm prompt exactly as under `moderate`; only the T2-alone case widens. This is the literal reading of "findings that would sit just below today's high-impact bar" from the task's own framing — a purely structural signal with no corroborating uncertainty is no longer, by itself, enough to interrupt the user.
+   - **`strict` (no confirm prompt for escalating findings, ever)** — a finding tripping any of T1-T3 is **never presented to the user**. Instead:
+     1. Write the node directly with a hedged, low-confidence `description`, reusing the exact hedging convention the Human-Oracle-Availability Limitation section already specifies (e.g. "unconfirmed — traces did not fully corroborate this," adapted to name the specific gap).
+     2. Call `elicitation-state.sh converge` directly — **do not call `elicitation-state.sh turn` for this node.** No confirmation round is spent; the node goes straight from "proposed" to "converged," never "pending":
+
+        ```bash
+        bash skills/j-uncharted/scripts/elicitation-state.sh converge --id <elicitation-id> --node <node-id> --note "auto-flagged under strict depth: <one-line reason, e.g. 'structurally central, traces disagree on scope'>"
+        ```
+     3. **Log the auto-flag** in the elicitation state's checkpoint data, the same way `moderate`/`shallow` auto-accepts are logged — this is an automatic decision, not a silent one, and stays auditable exactly like every other gating outcome.
+
+     Low-risk findings under `strict` are unaffected — they auto-accept exactly as under `moderate`/`shallow`. `strict` only changes what happens to the escalating case.
+
+   The fixed internal/external question template used whenever `shallow`/`moderate` gating does decide to prompt is `skills/j-uncharted/assets/NODE_QUESTION_TEMPLATE.md` (Step 5, `E40_S06_T03`) — dormant under `strict`, since no prompt ever fires there.
+5. **Confirm/correct, one round per call to `elicitation-state.sh turn`.** Never reached for a `strict`-depth candidate's escalating findings — those converge directly per Step 4 above. For a node requiring confirmation under `shallow`/`moderate`, do **not** present the draft with a fully open-ended "propose understanding, ask to confirm or correct" prompt. Instead use the fixed question set in `skills/j-uncharted/assets/NODE_QUESTION_TEMPLATE.md` (`E40_S06_T03`), selecting the variant by node kind:
+
+   - **Internal variant** — the node represents the candidate/service itself (the thing this investigation is about).
+   - **External variant** — the node represents a dependency or consumer the traces surfaced outside the candidate (something it calls, or something that calls it).
+
+   Present the drafted node/edge summary from Step 3 first, then ask the selected variant's fixed questions, then offer the same confirm / correct-with-detail / defer-as-unconfirmed / other choice as before (per the Interaction Pattern in `CLAUDE.md`) — the template file spells out both the questions and this response block verbatim, so read it rather than reconstructing either from memory. Each round, call:
 
    ```bash
    bash skills/j-uncharted/scripts/elicitation-state.sh turn --id <elicitation-id> --node <node-id>
@@ -233,7 +280,7 @@ Runs once per surviving candidate (a subsystem, a named flow, a directory) after
    ```
 
    Option 3 is the only way past the cap, and it is a per-node, explicit, one-time override — it does not raise the cap for the rest of the run.
-5. **On convergence** (confirmed, corrected-and-accepted, or resolved via the cap choice above), call:
+6. **On convergence** (confirmed, corrected-and-accepted, or resolved via the cap choice above), call:
 
    ```bash
    bash skills/j-uncharted/scripts/elicitation-state.sh converge --id <elicitation-id> --node <node-id> --note "<one-line summary of what was confirmed>"
@@ -252,9 +299,9 @@ A whole-codebase `onboard` conversation, or an investigation of a large director
   ```
 
   Idempotent — safe to call again on a resumed `<elicitation-id>` without resetting progress. Choose `<elicitation-id>` so it is stable and re-derivable across sessions (e.g. `onboard-<root-slug>-<date>`, or `segment-investigate-<target-slug>`), since a resuming session must be able to reconstruct it to call `init` again.
-- **`checkpoint` after every converged node and after the Directory Triage confirmation gate** — never only at the end. This is what makes a mid-run pause lossless: `checkpoint --id <id> --json <file>` merges arbitrary progress data (triage results, draft nodes not yet converged, anything else worth surviving a pause) into the state file.
+- **`checkpoint` after every converged node, after the Directory Triage confirmation gate, and after every Familiarity Check answer** — never only at the end. This is what makes a mid-run pause lossless: `checkpoint --id <id> --json <file>` merges arbitrary progress data (triage results, draft nodes not yet converged, per-candidate `verification_depth`, anything else worth surviving a pause) into the state file. `verification_depth` is stored as one object keyed by candidate id — `checkpoint.verification_depth.<candidate-id>` — and, per the script's own merge semantics (see its header), checking one candidate in never clobbers another candidate already recorded there.
 - **`pause` when a session must end before the elicitation has converged.** Immediately after calling `elicitation-state.sh pause --id <elicitation-id>`, write the scrum-master's own `SessionEnd` handoff (per `$([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md)`'s `handoffs/` convention) with `status: "elicitation_paused"` and both `elicitation_id` and `state_file` set — `hooks/on_session_end.sh` routes that into an `elicitation_resume` trigger on `scrum_triggers.jsonl`, which the next scrum-master session's Drain Scrum Triggers Queue procedure picks up (`agents/scrum-master.md`).
-- **On resume**, read `state_file` directly — every converged node, every flagged node, and the checkpoint data (including the confirmed directory-triage lists) are already there. Do not re-run Directory Triage or re-ask about an already-converged node; resume the Convergence Loop only for nodes still `pending` or explicitly deferred.
+- **On resume**, read `state_file` directly — every converged node, every flagged node, and the checkpoint data (including the confirmed directory-triage lists and any per-candidate `verification_depth` already recorded) are already there. Do not re-run Directory Triage, re-ask the Familiarity Check for a candidate already present under `checkpoint.verification_depth`, or re-ask about an already-converged node; resume the Convergence Loop only for nodes still `pending` or explicitly deferred, and only ask the Familiarity Check for a candidate that has neither.
 - **`complete` when every candidate has converged, been deferred, or been explicitly accepted past the cap.** The state file is left on disk afterward as an audit trail — nothing currently prunes a completed elicitation's state file.
 
 ---