@jenga-ai/agent 1.1.0 → 1.1.1

package/scripts/validate-board.sh

@@ -27,18 +27,76 @@ STATUS_VALUES = {
     "Done",
 }
 
+# E39 tiered item-level caution/escalation. crucial_level is OPTIONAL — absence means no
+# elevated caution. When present it must be one of these three values (see
+# templates/SCRUM_BOARD_SCHEMA.md). crucial_set_by / crucial_note are free-text fields that are
+# only recognised (not enum-validated) here; their "required when crucial_level is set" rule is
+# an authoring discipline documented in the schema, not mechanically enforced by this script —
+# the same treatment given to scope_rationale's "required when execution_scope is set" rule.
+CRUCIAL_LEVEL_VALUES = {
+    "advisory",
+    "gated",
+    "locked",
+}
+
+# Base keys shared by every item type, plus the E32 adaptive-execution-scope fields.
+#
+# The execution-scope fields are all OPTIONAL — a board file that omits them is valid and is
+# treated as execution_scope: task / needs_docs: true (see the backward-compatibility rule in
+# templates/SCRUM_BOARD_SCHEMA.md). They are listed here so that files which DO carry them are
+# not rejected as unknown.
+#
+# Two groups, distinguished by who writes them:
+#   - assigned at breakdown time by the scrum-master (execution_scope … epic_scope_approval)
+#   - written at runtime by /close-story and /do (actual_files_changed … divergence_flag)
+# Runtime fields appear only after a task has executed, so most task files will lack them.
+# task_changed_files is deliberately absent: it lives in the bundle manifest JSON
+# (project/queue/bundle-<E##_S##>.json), not in task frontmatter.
+EXECUTION_SCOPE_KEYS = {
+    "execution_scope", "needs_docs", "scope_rationale",
+    "jenga_assigned", "override_justification", "epic_scope_approval",
+}
+
+CLOSE_STORY_KEYS = {
+    "actual_files_changed", "actual_lines_delta", "scope_divergence_flag", "divergence_flag",
+}
+
+# E39 tiered item-level caution/escalation fields. OPTIONAL and story/task-only — epics do not
+# carry these; an epic's risk gating is already handled by epic_scope_approval. See
+# templates/SCRUM_BOARD_SCHEMA.md.
+#
+# crucial_declined / crucial_declined_note (E39_S02_T03) are a separate optional pair recording
+# that a scrum-master-proposed crucial_level was explicitly declined by the user for this item —
+# the durable decline-tracking mechanism that stops the breakdown step from re-proposing on a
+# later pass. Like crucial_set_by / crucial_note, they are free-text/recognised-not-enum-validated
+# here; their "required when crucial_declined: true" rule is an authoring discipline documented in
+# the schema, not mechanically enforced by this script.
+CRUCIAL_KEYS = {
+    "crucial_level", "crucial_set_by", "crucial_note",
+    "crucial_declined", "crucial_declined_note",
+}
+
 ALLOWED_KEYS = {
     "epic": {
         "id", "title", "status", "date_created", "date_started", "date_completed",
         "dates_previously_completed", "reopened_on", "reopened_reason", "stories", "docs",
+        "epic_scope_approval",
+        # OPTIONAL. Marks how the epic came to exist; only written by `/uncharted onboard`
+        # (value: backfilled). Absence means the epic was authored normally, so every existing
+        # epic that omits it stays valid. See templates/SCRUM_BOARD_SCHEMA.md.
+        "provenance",
     },
     "story": {
         "id", "epic_id", "title", "status", "date_created", "date_started", "date_completed",
         "dates_previously_completed", "reopened_on", "reopened_reason", "tasks", "docs",
+        "priority", "depends_on",
+        *CRUCIAL_KEYS,
     },
     "task": {
         "id", "story_id", "epic_id", "title", "status", "date_created", "date_started", "date_completed",
         "dates_previously_completed", "reopened_on", "reopened_reason", "assigned_to", "docs",
+        "depends_on",
+        *EXECUTION_SCOPE_KEYS, *CLOSE_STORY_KEYS, *CRUCIAL_KEYS,
     },
 }
 
@@ -152,6 +210,10 @@ def validate_file(source: Path):
     if status and status not in STATUS_VALUES:
         raise ValueError(f"{source}: invalid status '{status}'")
 
+    crucial_level = data.get("crucial_level")
+    if crucial_level and crucial_level not in CRUCIAL_LEVEL_VALUES:
+        raise ValueError(f"{source}: invalid crucial_level '{crucial_level}'")
+
     docs = data.get("docs", None)
     if docs is not None:
         validate_docs(source, docs)

package/scripts/with-lock.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# scripts/with-lock.sh — atomic, cross-platform exclusive file lock wrapper
+#
+# Usage:
+#   scripts/with-lock.sh <target-file> -- <command> [args...]
+#
+# Acquires an exclusive lock keyed to <target-file> before running <command>,
+# and always releases the lock afterward — on success, on failure, and on
+# signal (INT/TERM sent to this script are forwarded to the wrapped command,
+# which is then waited on before the lock is released — see the signal
+# handling note further down). The wrapped command's exit code is preserved
+# as this script's own exit code.
+#
+# This replaces the purely advisory "check for a .lock file, wait, retry,
+# then create/delete it yourself" convention previously described in
+# templates/SCRUM_BOARD_SCHEMA.md. That convention relied on every caller
+# implementing check-wait-retry-cleanup correctly, including on error paths,
+# with nothing to mechanically stop two writers from both deciding the lock
+# is free at the same time. This script enforces exclusivity instead.
+#
+# Lock primitive: `mkdir` on a lock directory, NOT `flock`. `flock` is a
+# Linux-only (util-linux) utility and is not present by default on macOS/BSD
+# (this repo runs on Darwin). POSIX `mkdir` is atomic on every platform this
+# repo targets: the kernel guarantees that when multiple processes race to
+# create the same directory, exactly one succeeds and every other call fails
+# with EEXIST. That atomicity — not any cooperative check beforehand — is
+# what makes this a real mutual-exclusion lock instead of advisory prose.
+#
+# Environment overrides (all optional):
+#   WITH_LOCK_TIMEOUT_SECONDS   Max time to wait for a held lock (default: 30)
+#   WITH_LOCK_POLL_SECONDS      Poll interval while waiting (default: 0.2)
+#   WITH_LOCK_STALE_SECONDS     Age after which a still-held lock is treated
+#                               as abandoned (crashed holder) and reclaimed
+#                               (default: 60)
+#
+# Exit codes:
+#   0    lock acquired, command ran, exit code is the command's own
+#   1    invalid usage
+#   2    could not acquire the lock within the timeout — the command was
+#        NEVER run (fail safe; no partial or silently-clobbered write)
+#   *    otherwise, the wrapped command's own exit code
+
+set -u
+
+usage() {
+  echo "Usage: $0 <target-file> -- <command> [args...]" >&2
+  exit 1
+}
+
+[ "$#" -ge 1 ] || usage
+TARGET_FILE="$1"
+shift
+
+[ "${1:-}" = "--" ] || usage
+shift
+
+[ "$#" -ge 1 ] || usage
+
+TIMEOUT_SECONDS="${WITH_LOCK_TIMEOUT_SECONDS:-30}"
+POLL_SECONDS="${WITH_LOCK_POLL_SECONDS:-0.2}"
+STALE_SECONDS="${WITH_LOCK_STALE_SECONDS:-60}"
+
+LOCK_DIR="${TARGET_FILE}.lock.d"
+LOCK_PID_FILE="${LOCK_DIR}/pid"
+
+now_epoch() {
+  date +%s
+}
+
+# Portable mtime lookup: GNU stat (Linux) uses -c, BSD stat (macOS) uses -f.
+# Try GNU form first, fall back to BSD form. Echoes nothing (and returns
+# non-zero) if the directory vanished in the meantime.
+lock_mtime_epoch() {
+  stat -c %Y "$LOCK_DIR" 2>/dev/null || stat -f %m "$LOCK_DIR" 2>/dev/null
+}
+
+# If the held lock looks abandoned (older than STALE_SECONDS), reclaim it.
+# This does NOT grant the lock by itself — it only clears the way. The next
+# mkdir attempt in the polling loop is still the sole arbiter of who
+# proceeds, so simultaneous reclaim attempts by multiple waiters never let
+# more than one of them through.
+maybe_reclaim_stale_lock() {
+  local mtime now age
+  mtime="$(lock_mtime_epoch)" || return 0
+  now="$(now_epoch)"
+  age=$(( now - mtime ))
+  if [ "$age" -ge "$STALE_SECONDS" ]; then
+    echo "with-lock: reclaiming stale lock '$LOCK_DIR' (age ${age}s >= ${STALE_SECONDS}s)" >&2
+    rm -rf "$LOCK_DIR" 2>/dev/null
+  fi
+}
+
+acquire_lock() {
+  local start now elapsed
+  start="$(now_epoch)"
+  while true; do
+    if mkdir "$LOCK_DIR" 2>/dev/null; then
+      echo "$$" > "$LOCK_PID_FILE" 2>/dev/null || true
+      return 0
+    fi
+
+    maybe_reclaim_stale_lock
+
+    now="$(now_epoch)"
+    elapsed=$(( now - start ))
+    if [ "$elapsed" -ge "$TIMEOUT_SECONDS" ]; then
+      return 1
+    fi
+    sleep "$POLL_SECONDS" 2>/dev/null || sleep 1
+  done
+}
+
+release_lock() {
+  rm -rf "$LOCK_DIR" 2>/dev/null
+}
+
+if ! acquire_lock; then
+  echo "with-lock: failed to acquire lock on '$TARGET_FILE' within ${TIMEOUT_SECONDS}s (lock dir: $LOCK_DIR) — command was not run" >&2
+  exit 2
+fi
+
+# Always release the lock on exit, regardless of how the wrapped command
+# (or this script itself) terminates.
+trap release_lock EXIT
+
+# Signal handling note: the wrapped command is run in the background and
+# waited on explicitly (rather than exec'd directly in the foreground) so
+# that INT/TERM delivered to this script are handled promptly. Bash defers
+# non-EXIT traps until a foreground command completes, so a script that
+# instead ran `"$@"` directly in the foreground would not react to a signal
+# sent to its own PID until the wrapped command finished on its own —
+# release would then only happen once the command exited naturally (or, in
+# the worst case, once WITH_LOCK_STALE_SECONDS elapsed and another waiter
+# reclaimed the lock). Backgrounding + `wait` avoids that: the trap fires as
+# soon as the signal arrives, forwards it to the child, waits for the child
+# to actually exit, then this script exits (triggering the EXIT trap above,
+# which releases the lock).
+CHILD_PID=""
+
+forward_signal_and_exit() {
+  local sig="$1" exit_code="$2"
+  if [ -n "$CHILD_PID" ]; then
+    kill -s "$sig" "$CHILD_PID" 2>/dev/null
+    wait "$CHILD_PID" 2>/dev/null
+  fi
+  exit "$exit_code"
+}
+
+trap 'forward_signal_and_exit TERM 143' TERM
+trap 'forward_signal_and_exit INT 130' INT
+
+"$@" &
+CHILD_PID=$!
+wait "$CHILD_PID"
+status=$?
+CHILD_PID=""
+
+exit "$status"

package/scripts/worktree-remove-guard.sh

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+# scripts/worktree-remove-guard.sh — hard-block-by-default liveness
+# precondition for `git worktree remove`, wired into the `WorktreeRemove`
+# hook in (root, canonical) settings.json.
+#
+# Why this exists: see project/board/epics/E37_inter-agent-completion-signaling.md
+# and project/board/stories/E37_S03_worktree-remove-liveness-precondition.md.
+# `git worktree remove --force` previously ran unconditionally as soon as
+# the WorktreeRemove hook fired, with no precondition of any kind — this is
+# how a 2026-08-25 incident's orphaned shell polling loops got their cwd
+# deleted out from under them. This script now runs
+# scripts/check-worktree-liveness.sh (E37_S03_T01) first, and only proceeds
+# to `git worktree remove --force` if that check reports the path clear (or
+# an explicit override is set).
+#
+# Invocation modes:
+#
+#   1. Hook mode (no positional worktree-path argument): reads a JSON
+#      payload from stdin and extracts `.worktree_path` (required) and an
+#      optional `.force_ignore_liveness` boolean field. This is how the
+#      WorktreeRemove hook actually invokes this script — matching the
+#      pre-existing `jq -r '.worktree_path'` convention this script
+#      replaces. Note: the native harness's WorktreeRemove hook JSON
+#      schema is outside this repo's control (its `ExitWorktree` tool
+#      exposes only `action`/`discard_changes`, no pass-through custom
+#      field), so `.force_ignore_liveness` on the payload is supported for
+#      any caller that *does* control the JSON directly (e.g. a script
+#      invoking this guard outside the native tool), but is not the primary
+#      override mechanism for the native hook path — see the environment
+#      variable below for that.
+#
+#   2. CLI mode (direct/manual invocation — used for this script's own
+#      testing and any other scripted use outside the hook):
+#        scripts/worktree-remove-guard.sh [--force-ignore-liveness] <worktree-path>
+#
+# Override (works in both modes): set the environment variable
+#   WORKTREE_REMOVE_FORCE_IGNORE_LIVENESS=1
+# immediately before invoking this script (directly, or before whatever
+# triggers the WorktreeRemove hook). Accepted truthy values: 1, true, TRUE,
+# True, yes, YES. This is the one lever guaranteed to work regardless of
+# invocation mode or what JSON the calling harness does or doesn't pass
+# through. It must be set explicitly on each invocation — it is never read
+# from a file, never cached, and never a default; every invocation re-reads
+# the environment fresh.
+#
+# Decision logic:
+#   - If an override is set (CLI flag, JSON field, or env var): skip the
+#     liveness check, print a visible bypass notice to stderr, and run
+#     `git worktree remove --force <path>`.
+#   - Otherwise, run scripts/check-worktree-liveness.sh <path>. ANY non-zero
+#     exit blocks removal by default — not just exit 1 ("live process
+#     found"), but also exit 2/3/4 (usage error / invalid path / liveness
+#     indeterminate), since none of those represent "the path is
+#     affirmatively clear," consistent with that script's own fail-closed
+#     design. `git worktree remove` is never invoked in this branch. The
+#     liveness check's own PID/command output (or error message) is
+#     surfaced to the caller, plus a note on how to override.
+#   - On a clear (exit 0) result: proceed to `git worktree remove --force
+#     <path>` exactly as the old unconditional one-liner did, with no extra
+#     output — the "clear worktree" case must behave exactly as before,
+#     with no added friction.
+#
+# Exit codes:
+#   *   whatever `git worktree remove --force <path>` itself exits with, if
+#       removal proceeded (clear path, or override set)
+#   1   blocked — liveness check reported non-zero and no override was set;
+#       git worktree remove was NOT run
+#   2   usage error — no worktree path resolvable from CLI args or stdin
+#       JSON, or an unrecognized flag
+
+set -u
+
+SCRIPT_NAME="worktree-remove-guard.sh"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd -P)"
+LIVENESS_SCRIPT="$SCRIPT_DIR/check-worktree-liveness.sh"
+
+# Resolve a safe anchor directory to relocate this process's own cwd into
+# further below (see the "Caller-cwd self-detection hardening" block after
+# argument parsing) — the main repository's working-tree root, derived from
+# the shared git common dir so it resolves correctly regardless of which
+# worktree this script's own cwd currently happens to be in. Must be
+# computed now, from the ORIGINAL cwd, since `git rev-parse` depends on
+# being inside a git working tree.
+GIT_COMMON_DIR_RAW="$(git rev-parse --git-common-dir 2>/dev/null)"
+SAFE_ANCHOR=""
+if [ -n "$GIT_COMMON_DIR_RAW" ]; then
+  SAFE_ANCHOR="$(cd "$(dirname "$GIT_COMMON_DIR_RAW")" >/dev/null 2>&1 && pwd -P)"
+fi
+
+FORCE_OVERRIDE=0
+WORKTREE_PATH=""
+
+# --- Parse CLI-style args, if any. ---
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --force-ignore-liveness)
+      FORCE_OVERRIDE=1
+      shift
+      ;;
+    --)
+      shift
+      break
+      ;;
+    -*)
+      echo "$SCRIPT_NAME: unknown flag '$1'" >&2
+      exit 2
+      ;;
+    *)
+      break
+      ;;
+  esac
+done
+if [ "$#" -ge 1 ]; then
+  WORKTREE_PATH="$1"
+fi
+
+# --- Hook mode: no positional worktree path given, so read the JSON
+#     payload the WorktreeRemove hook receives on stdin. ---
+if [ -z "$WORKTREE_PATH" ]; then
+  if [ -t 0 ]; then
+    echo "$SCRIPT_NAME: no worktree path given (expected a positional argument, or JSON on stdin with a 'worktree_path' field)" >&2
+    exit 2
+  fi
+  PAYLOAD="$(cat)"
+  WORKTREE_PATH="$(printf '%s' "$PAYLOAD" | jq -r '.worktree_path // empty' 2>/dev/null)"
+  if [ "$FORCE_OVERRIDE" -eq 0 ]; then
+    PAYLOAD_OVERRIDE="$(printf '%s' "$PAYLOAD" | jq -r 'if .force_ignore_liveness == true then "true" else "false" end' 2>/dev/null)"
+    [ "$PAYLOAD_OVERRIDE" = "true" ] && FORCE_OVERRIDE=1
+  fi
+fi
+
+if [ -z "$WORKTREE_PATH" ]; then
+  echo "$SCRIPT_NAME: no worktree path provided (expected a positional argument, or a 'worktree_path' field on stdin JSON)" >&2
+  exit 2
+fi
+
+# Resolve WORKTREE_PATH to an absolute, symlink-resolved path NOW, while
+# still in the original cwd — we're about to relocate this process's own
+# cwd away (hardening below), and a relative path would no longer resolve
+# correctly against the caller's original cwd afterward. (In practice the
+# hook always supplies an absolute path — see WorktreeCreate's own
+# `DIR="$JENGA_PROJECT_DIR/.claude/worktrees/$NAME"` construction — this
+# also makes relative paths work correctly for CLI-mode/manual use.) If
+# resolution fails (path does not exist), fall through with the original,
+# unresolved string; check-worktree-liveness.sh and/or `git worktree
+# remove` will report the appropriate error themselves.
+WORKTREE_PATH_RESOLVED="$(cd "$WORKTREE_PATH" 2>/dev/null && pwd -P)"
+[ -n "$WORKTREE_PATH_RESOLVED" ] && WORKTREE_PATH="$WORKTREE_PATH_RESOLVED"
+
+# --- Environment override — checked last so it can force the bypass
+#     regardless of how the path was supplied. ---
+case "${WORKTREE_REMOVE_FORCE_IGNORE_LIVENESS:-}" in
+  1|true|TRUE|True|yes|YES)
+    FORCE_OVERRIDE=1
+    ;;
+esac
+
+# Caller-cwd self-detection hardening (this script's own layer of it — see
+# the matching comment block in check-worktree-liveness.sh for the
+# underlying check script's own layer, which protects only its own spawned
+# subprocesses). THIS script is what actually invokes that check below —
+# if this script's own process was itself launched with a cwd already
+# inside the worktree being removed (a real, expected scenario: the
+# WorktreeRemove hook may fire from a session whose cwd is inside the
+# worktree about to be removed, right before cleanup), this script's own
+# PID would itself be "a live process rooted in" that path at the moment
+# the check runs — check-worktree-liveness.sh's $$-exclusion only ever
+# covers its own PID, not its caller's. Relocating to the main repo root
+# (resolved above, before WORKTREE_PATH is used any further) — rather than
+# to `/` — means both the liveness check AND the eventual `git worktree
+# remove` below keep working normally (git needs to run from inside some
+# working tree), while still guaranteeing neither this script's own process
+# nor the check script it spawns as a child can be cwd'd inside the target,
+# regardless of what cwd the original caller had. Falls back to `/` only if
+# the repo-root anchor could not be resolved (a degenerate case; `git
+# worktree remove` itself will then fail with its own clear error).
+# (Residual, out-of-our-control limitation: if some ancestor further up the
+# process chain — e.g. the harness's own hook-runner shell, if it stays
+# resident rather than exec'ing straight into this script — independently
+# keeps its own cwd inside the target and stays alive while waiting on this
+# script, that ancestor is a separate process this script cannot
+# retroactively relocate; the courtesy $$-style exclusion pattern used
+# throughout these two scripts only ever covers processes each script
+# itself controls.)
+cd "${SAFE_ANCHOR:-/}" 2>/dev/null || true
+
+if [ "$FORCE_OVERRIDE" -eq 1 ]; then
+  echo "$SCRIPT_NAME: liveness check explicitly bypassed (--force-ignore-liveness / WORKTREE_REMOVE_FORCE_IGNORE_LIVENESS) for '$WORKTREE_PATH' — proceeding to remove without checking for live processes." >&2
+  git worktree remove --force "$WORKTREE_PATH"
+  exit $?
+fi
+
+LIVENESS_OUTPUT="$("$LIVENESS_SCRIPT" "$WORKTREE_PATH" 2>&1)"
+LIVENESS_EXIT=$?
+
+if [ "$LIVENESS_EXIT" -eq 0 ]; then
+  git worktree remove --force "$WORKTREE_PATH"
+  exit $?
+fi
+
+echo "$SCRIPT_NAME: BLOCKED — not removing '$WORKTREE_PATH' (liveness check exited $LIVENESS_EXIT):" >&2
+[ -n "$LIVENESS_OUTPUT" ] && echo "$LIVENESS_OUTPUT" >&2
+echo "$SCRIPT_NAME: git worktree remove was NOT run. If this is expected (e.g. a known, accepted background process), re-run with an explicit override: pass --force-ignore-liveness (CLI mode), a true 'force_ignore_liveness' field on the input JSON (hook mode), or set WORKTREE_REMOVE_FORCE_IGNORE_LIVENESS=1 in the environment (either mode)." >&2
+exit 1

package/skills/clearify/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: clearify
+description: Clarifies ambiguous, dense, or under-specified prompts and conversation on request — inspects an attached prompt or falls back to the current conversation and surfaces plain-language clarifications with examples.
+keywords:
+  - clarify this
+  - clarify
+  - what do you mean
+  - I don't understand
+  - wtf
+  - explain that again
+  - can you simplify
+examples:
+  - "clarify this"
+  - "clearify the last message"
+  - "wtf does this mean"
+  - "I don't understand what you're asking me to do here"
+alias: wtf
+---
+
+# Clearify — Ambiguity Clarification
+
+> **Note on the `alias: wtf` frontmatter field:** this repo has no runtime mechanism that reads an `alias` key to route slash commands — no existing `SKILL.md` implements one, and `project/configs/workflow.json` has no alias registry. The field here documents the intended relationship only. `/wtf` is made invocable as a working alias by the companion skill folder at `skills/wtf/SKILL.md`, which delegates to these same instructions.
+
+## Instructions
+
+1. **Determine the target content.**
+   - If the user attached a prompt, file, or pasted block of text with this invocation, treat that as the target content.
+   - Otherwise, fall back to the most recent user message, plus any surrounding conversation context needed to make sense of it (e.g. the message it's replying to, an earlier instruction it references).
+   - Note: this is the only fallback distinction that matters — do not ask the user which content to clarify; infer it from what's available.
+
+2. **Identify ambiguous or dense formulations** in the target content. Look for:
+   - Jargon or domain-specific terms used without definition
+   - Unclear pronouns or references ("it", "that", "this one" — where the referent isn't obvious)
+   - Compound asks (multiple distinct requests bundled into one sentence)
+   - Unstated assumptions (the request depends on context the reader doesn't have)
+   - Vague quantifiers or qualifiers ("soon", "a bit", "some of them") where precision matters
+   - Overloaded or dense sentences that pack too much meaning into too little structure
+
+3. **For each ambiguous item found, output a structured block** with:
+   - **Plain-language clarification** — what it most likely means, stated simply and directly
+   - **Simplified restatement** — the original phrasing rewritten in plain terms
+   - **Additional context** — relevant background the user may be missing (why this term/reference matters, what it typically implies)
+   - **Example(s)** — a concrete worked example, included only where it would actually help clarify the specific ambiguity — skip this sub-section for an item if an example wouldn't add value, rather than manufacturing a weak one
+
+4. **Format the output so it's scannable.** Use a header or bold label per ambiguous item (e.g. `### 1. "the usual setup"` or `**1. "the usual setup"**`) — never collapse multiple ambiguous items into a single unstructured paragraph. If there are multiple items, number them in the order they appear in the source content.
+
+5. **Handle the zero-ambiguity case explicitly.** If nothing in the target content is actually ambiguous, dense, or under-specified, say so plainly — e.g. "Nothing here looks ambiguous — the request is clear as written." Do not manufacture findings just to have something to report.
+
+## Examples
+- `/clearify` — Clarify the most recent user message / relevant conversation context
+- `/clearify <pasted text>` — Clarify the attached text directly
+- `/wtf` — Alias for `/clearify`, invoked via the companion skill in `skills/wtf/`

package/skills/commit/SKILL.md

@@ -18,7 +18,7 @@ examples:
 
 When invoked with the `--inline` flag OR when the environment variable `JENGA_COMMIT_INLINE=1` is set, execute inline mode:
 
-1. **Skip** the user-action prerequisites check (step 1 in normal mode). No `_INSTRUCTIONS.md` lookup is performed.
+1. **Skip** the reconcile step, the `/doc-sync` scan, and the user-action prerequisites check (steps 1-3 in normal mode). No `/reconcile` invocation, `/doc-sync` invocation, or `_INSTRUCTIONS.md` lookup is performed — inline tasks are single, already-scoped-small changes that reconcile and doc-sync would add overhead to, not risk, disproportionate to the size of the change.
 2. **Skip** any worktree merge logic — inline tasks execute in the main session with no dedicated worktree to merge.
 3. Stage all changed files relevant to the task (use `git add -A` or specific files if a list was provided by the caller).
 4. Commit using the EST naming convention:
@@ -36,12 +36,21 @@ If `--inline` is absent **and** `JENGA_COMMIT_INLINE` is not set (or is not `1`)
 
 If no epic, task, or story has been implemented, exit with the message: "No implementation to commit."
 
-1. **Verify user-action prerequisites** — Check whether an `_INSTRUCTIONS.md` file exists for this task at `project/board/tasks/<E##_S##_T##>_INSTRUCTIONS.md`. If the task has out-of-scope prerequisites but no instructions file was created, create one now using `assets/user_instructions_template.md`. If one already exists, surface it to the user as a reminder. (The developer should have created this file during task intake — this is a final safety check.)
+1. **Reconcile first** — Invoke the `/reconcile` skill before any other action, so the board is never committed in a drifted state.
+   - **If reconcile detects and corrects drift** — inform the user what changed (e.g. demoted/promoted statuses, merged orphaned worktrees, cleaned `todo.md` entries) before proceeding.
+   - **If reconcile finds no drift** — continue silently to the next step.
 
-2. **Commit** using the following format:
+2. **Doc-sync scan, scoped to this change (report-only, non-blocking)** — Invoke `/doc-sync` scoped via its `source:` argument to the files actually changed by the work being committed — never a full-repo scan. Determine the changed-file list from the work being committed (e.g. `git diff --name-only HEAD` combined with untracked files from `git status --porcelain`, or the task's known changed-file set when commit context already identifies them) and pass it as `source:` so doc-sync only analyses what this commit touches.
+   - **Design decision — report-only, not blocking:** doc-sync's own step 5 ("report findings, ask before applying") is a human-approval gate. When invoked from `/commit`, doc-sync runs only through its own step 5 (report the drift findings) and explicitly does **not** proceed to its step 6 (apply updates) as part of this flow — `/commit` never surfaces doc-sync's apply-confirmation prompt mid-commit. *Rationale: nesting a second approval gate inside an already-in-flight commit either stalls a flow the user expected to complete in one shot, or trains the user to reflexively decline the nested prompt just to get their commit through. Report-only surfaces documentation drift at the cheapest possible moment to notice it — right when the change is fresh — without forcing an apply/skip decision under commit pressure; the user reviews the findings and runs `/doc-sync` standalone afterward if they want to apply them.* This introduces no change to `/doc-sync`'s own step 5 approval semantics and no new auto-apply flag — `/commit` simply never invites it past step 5.
+   - **If doc-sync reports drift findings** — surface them to the user as part of the commit output (informational), then continue to the next step regardless of the findings.
+   - **If doc-sync reports no drift** — continue silently to the next step.
+
+3. **Verify user-action prerequisites** — Check whether an `_INSTRUCTIONS.md` file exists for this task at `project/instructions/<E##_S##_T##>_INSTRUCTIONS.md`. If the task has out-of-scope prerequisites but no instructions file was created, create one now using `assets/user_instructions_template.md`. If one already exists, surface it to the user as a reminder. (The developer should have created this file during task intake — this is a final safety check.)
+
+4. **Commit** using the following format:
    - **Epic:** `epic(<Epic Title>): <MAX_50_CHAR_SUMMARY>`
    - **Task/Story:** `story(<Epic Title>_<Story Title>): <MAX_50_CHAR_SUMMARY>`
    
    **Fallback: Group changes logically** — prefer one commit per coherent unit of work, but don't force splits. When in doubt, keep it together.
 
-3. **Check for next epic** — If a new epic is to be started, inform the user that a new conversation should be initiated. If there are no subsequent epics left, show the message: "All Done! 🎉"
+5. **Check for next epic** — If a new epic is to be started, inform the user that a new conversation should be initiated. If there are no subsequent epics left, show the message: "All Done! 🎉"

package/skills/distribute/CONFIG_SCHEMA.md

@@ -1,6 +1,6 @@
 # jenga.config.json — Schema Reference
 
-This document is the canonical reference for the `jenga.config.json` file written into **consuming projects** during framework distribution. The file is created and maintained by `distribute-changes.sh`; it should not be edited by hand.
+This document is the canonical reference for the `jenga.config.json` file written into **consuming projects** during framework distribution. The file is created and maintained by `distribute-changes.sh`, with the `project_files_visibility` field written by `skills/init/scripts/apply-project-visibility.sh` during `/init`; it should not be edited by hand.
 
 ---
 
@@ -27,7 +27,8 @@ This document is the canonical reference for the `jenga.config.json` file writte
   "version": "2.3.1",
   "updated_at": "2026-08-11",
   "last_distributed": "2026-08-11T10:00:00Z",
-  "source": "private"
+  "source": "private",
+  "project_files_visibility": "visible"
 }
 ```
 
@@ -43,6 +44,61 @@ This document is the canonical reference for the `jenga.config.json` file writte
 | `updated_at` | string (ISO 8601 date) | yes | — | Date of the last successful distribution, in `YYYY-MM-DD` format. Does **not** include a time component. |
 | `last_distributed` | string (ISO 8601 datetime) | yes | — | Full UTC timestamp of the last successful distribution, in `YYYY-MM-DDTHH:MM:SSZ` format. Provides more precision than `updated_at` and is useful for audit and ordering purposes. |
 | `source` | string | yes | `"private"` | Distribution channel. Always `"private"` for projects that receive updates via the filesystem distribution mechanism. Distinguishes these projects from any future npm-installed consumers. Do not change this value manually. |
+| `project_files_visibility` | string (enum) | no | `"visible"` | How JengaAgent's own working files appear in the consuming project. Exactly one of `visible` or `ignored` — no other value is accepted. Written by `/init`, not by distribution. See [Project files visibility](#project-files-visibility) below. |
+
+---
+
+## Project files visibility
+
+`project_files_visibility` controls how JengaAgent's own working files — the `project/` tree containing the scrum board, `todo.md`, `queue/`, `rapports/`, and `logs/` — appear in a consuming project.
+
+This is distinct from `target_dir`. `target_dir` governs where the **distributed framework files** (skill and agent definitions) land; `project_files_visibility` governs the **working tree** that accumulates as the framework is used.
+
+### Allowed values
+
+Exactly two values are accepted. Any other value is rejected with a non-zero exit code.
+
+| Value | On-disk effect |
+|---|---|
+| `visible` | Working files stay at `project/`, tracked and visible in directory listings. Nothing on disk is changed. |
+| `ignored` | Working files stay at `project/`, but `project/` is appended to the project's `.gitignore`, so they exist on disk and are never committed. |
+
+#### Withdrawn: `hidden`
+
+A third value, `hidden` (dot-prefixing `project/` to `.project/`, following the
+same convention already used for `.agents/` and `.claude/`), was implemented
+and tester-verified to produce the correct on-disk layout, but was withdrawn
+before release because it is functionally broken at runtime:
+
+- `scripts/board_resolver.sh` hardcodes `project/configs/workflow.json` as its
+  config path. It never locates the rewritten `.project/configs/workflow.json`,
+  silently falls back to a default that no longer exists, and exits `0` —
+  a silent wrong answer rather than a hard failure.
+- `hooks/on_session_end.sh` hardcodes and unconditionally creates
+  `project/rapports/problems`, `project/queue`, and `project/logs`. Under
+  `hidden` mode this recreates a shadow `project/` tree on the very next
+  session end, splitting runtime state across `project/` and `.project/` —
+  the clutter the mode was meant to remove reappears, and some agent output
+  (e.g. queue triggers) is written to the tree the board no longer lives in.
+
+Full findings: `project/rapports/problems/E31_S05_T01-hidden-mode-path-resolution-gaps.md`.
+
+`hidden` is not offered by the `/init` prompt and is not accepted by
+`apply-project-visibility.sh`. Reintroducing it requires fixing both hardcoded
+paths above (routing them through `workflow.json` instead) — tracked as a
+follow-up `/todo` item rather than built as part of this field.
+
+### Default
+
+The default is **`visible`**, used whenever `/init` runs non-interactively or the user is not prompted.
+
+`visible` is the only value that is a genuine no-op on disk, so an unattended run can never silently relocate a user's directories or mutate their `.gitignore`. It also matches the behaviour of every project scaffolded before this field existed, making it backward-compatible for any consuming project whose `jenga.config.json` predates the field — an absent field is read as `visible`.
+
+### Who writes it
+
+The field is written during `/init` by `skills/init/scripts/apply-project-visibility.sh`, which also performs the corresponding on-disk change. The script merges the field into any existing `jenga.config.json` rather than overwriting the file, since `/init` normally runs before the first `/distribute` has created it.
+
+Changing the value after the initial `/init` is not currently supported — there is no toggle or migration path. Re-running the applier with a different mode is not a supported upgrade route.
 
 ---
 
@@ -59,6 +115,8 @@ When `distribute-changes.sh` runs against a project for the first time and no `j
 
 The directory referenced by `target_dir` is created if it does not already exist.
 
+> **Known gap:** `distribute-changes.sh` rebuilds `jenga.config.json` from scratch on every run and emits only the six fields above, so a `project_files_visibility` value written by `/init` is dropped by the next `/distribute`. Making the rebuild preserve fields it does not own is tracked as follow-up work; until then, treat the on-disk layout (not the config field) as the source of truth for which mode a project is in.
+
 ---
 
 ## Atomic write mechanism