@jenga-ai/agent 1.0.1 → 1.1.1

package/skills/close-story/scripts/compute-scope-divergence.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# compute-scope-divergence.sh — Compute scope_divergence_flag for a task
+#
+# Usage: compute-scope-divergence.sh <execution_scope> <actual_files_changed> <actual_lines_delta>
+#
+# Reads project/configs/scope-thresholds.json (resolved from git root) and compares
+# the supplied diff stats against the thresholds that apply to <execution_scope>.
+#
+# Scope logic:
+#   inline  — divergence if actual_files_changed > inline_max_files
+#                       OR actual_lines_delta    > inline_max_lines
+#   story   — divergence if actual_files_changed > story_max_files
+#   task    — no automatic threshold: always false
+#   epic    — no automatic threshold: always false
+#   (any other value) — treated as task; always false
+#
+# Prints "true" or "false" on stdout and exits 0.
+# If the config file is missing or cannot be parsed, prints "false" (non-blocking),
+# emits a warning to stderr, and exits 0.
+#
+# Exit codes:
+#   0 — success (including graceful degradation when config is absent/malformed)
+#   1 — invalid argument count
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Argument validation
+# ---------------------------------------------------------------------------
+
+if [[ $# -ne 3 ]]; then
+  echo "Usage: $(basename "$0") <execution_scope> <actual_files_changed> <actual_lines_delta>" >&2
+  echo "  Example: $(basename "$0") inline 2 35" >&2
+  exit 1
+fi
+
+EXECUTION_SCOPE="${1}"
+ACTUAL_FILES="${2}"
+ACTUAL_LINES="${3}"
+
+# ---------------------------------------------------------------------------
+# Short-circuit: task and epic scopes never flag divergence
+# ---------------------------------------------------------------------------
+
+if [[ "$EXECUTION_SCOPE" == "task" || "$EXECUTION_SCOPE" == "epic" ]]; then
+  echo "false"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Locate the config file (relative to git root)
+# ---------------------------------------------------------------------------
+
+GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
+
+if [[ -z "$GIT_ROOT" ]]; then
+  echo "WARNING: Not inside a git repository; cannot locate scope-thresholds.json. Skipping divergence flag." >&2
+  echo "false"
+  exit 0
+fi
+
+CONFIG_FILE="${GIT_ROOT}/project/configs/scope-thresholds.json"
+
+if [[ ! -f "$CONFIG_FILE" ]]; then
+  echo "WARNING: scope-thresholds.json not found at '${CONFIG_FILE}'. Skipping divergence flag." >&2
+  echo "false"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Parse thresholds (jq preferred, plain shell fallback)
+# ---------------------------------------------------------------------------
+
+INLINE_MAX_FILES=""
+INLINE_MAX_LINES=""
+STORY_MAX_FILES=""
+
+if command -v jq >/dev/null 2>&1; then
+  INLINE_MAX_FILES=$(jq -r '.inline_max_files // empty' "$CONFIG_FILE" 2>/dev/null || true)
+  INLINE_MAX_LINES=$(jq -r '.inline_max_lines // empty' "$CONFIG_FILE" 2>/dev/null || true)
+  STORY_MAX_FILES=$(jq -r  '.story_max_files  // empty' "$CONFIG_FILE" 2>/dev/null || true)
+else
+  # Plain shell fallback: grep for the numeric value on the matching key line
+  INLINE_MAX_FILES=$(grep '"inline_max_files"' "$CONFIG_FILE" | grep -o '[0-9][0-9]*' | head -1 || true)
+  INLINE_MAX_LINES=$(grep '"inline_max_lines"' "$CONFIG_FILE" | grep -o '[0-9][0-9]*' | head -1 || true)
+  STORY_MAX_FILES=$(grep  '"story_max_files"'  "$CONFIG_FILE" | grep -o '[0-9][0-9]*' | head -1 || true)
+fi
+
+# Validate that all required thresholds were parsed
+if [[ -z "$INLINE_MAX_FILES" || -z "$INLINE_MAX_LINES" || -z "$STORY_MAX_FILES" ]]; then
+  echo "WARNING: scope-thresholds.json is malformed or missing required keys (inline_max_files, inline_max_lines, story_max_files). Skipping divergence flag." >&2
+  echo "false"
+  exit 0
+fi
+
+# Ensure values are integers
+if ! [[ "$INLINE_MAX_FILES" =~ ^[0-9]+$ && "$INLINE_MAX_LINES" =~ ^[0-9]+$ && "$STORY_MAX_FILES" =~ ^[0-9]+$ ]]; then
+  echo "WARNING: Non-integer threshold value found in scope-thresholds.json. Skipping divergence flag." >&2
+  echo "false"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Apply per-scope divergence logic
+# ---------------------------------------------------------------------------
+
+case "$EXECUTION_SCOPE" in
+  inline)
+    if [[ "$ACTUAL_FILES" -gt "$INLINE_MAX_FILES" ]] || [[ "$ACTUAL_LINES" -gt "$INLINE_MAX_LINES" ]]; then
+      echo "true"
+    else
+      echo "false"
+    fi
+    ;;
+  story)
+    if [[ "$ACTUAL_FILES" -gt "$STORY_MAX_FILES" ]]; then
+      echo "true"
+    else
+      echo "false"
+    fi
+    ;;
+  *)
+    # Unknown scope — treat conservatively as no divergence
+    echo "false"
+    ;;
+esac
+
+exit 0

package/skills/close-story/scripts/extract-diff-stats.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+STORY_ID="${1:-}"
+DATE_STARTED="${2:-}"
+DATE_COMPLETED="${3:-}"
+
+if [[ -z "$STORY_ID" ]]; then
+  echo "Usage: extract-diff-stats.sh <story-id> [<date_started> <date_completed>]" >&2
+  exit 1
+fi
+
+# Primary query — EST pattern match
+# Collect all --stat output for commits matching the story ID pattern
+STAT_OUTPUT=$(git log --all --stat --no-merges --grep="$STORY_ID" --pretty=format:"COMMIT:%H %s" 2>/dev/null || true)
+
+# Parse insertions and deletions from --stat lines
+# --stat lines look like: " 3 files changed, 45 insertions(+), 12 deletions(-)"
+# Using portable grep (BSD and GNU compatible) instead of grep -oP
+DIFF_ADDED=$(echo "$STAT_OUTPUT" | (grep -o '[0-9]* insertion' || true) | awk '{sum+=$1} END {print sum+0}')
+DIFF_REMOVED=$(echo "$STAT_OUTPUT" | (grep -o '[0-9]* deletion' || true) | awk '{sum+=$1} END {print sum+0}')
+COMMITS_MATCHED=$(git log --all --no-merges --grep="$STORY_ID" --pretty=format:"%H" 2>/dev/null | wc -l | tr -d ' ')
+
+# Secondary query — date-window unmatched count
+if [[ -n "$DATE_STARTED" && -n "$DATE_COMPLETED" ]]; then
+  ALL_IN_WINDOW=$(git log --all --no-merges \
+    --since="$DATE_STARTED" \
+    --until="${DATE_COMPLETED}T23:59:59" \
+    --pretty=format:"%H" 2>/dev/null || true)
+
+  MATCHED_HASHES=$(git log --all --no-merges --grep="$STORY_ID" --pretty=format:"%H" 2>/dev/null || true)
+
+  COMMITS_UNMATCHED=0
+  while IFS= read -r hash; do
+    [[ -z "$hash" ]] && continue
+    if ! echo "$MATCHED_HASHES" | grep -q "^$hash$"; then
+      COMMITS_UNMATCHED=$((COMMITS_UNMATCHED + 1))
+    fi
+  done <<< "$ALL_IN_WINDOW"
+else
+  COMMITS_UNMATCHED="unknown"
+fi
+
+# Output structured results
+echo "diff_added: $DIFF_ADDED"
+echo "diff_removed: $DIFF_REMOVED"
+echo "commits_matched: $COMMITS_MATCHED"
+echo "commits_unmatched_in_window: $COMMITS_UNMATCHED"

package/skills/close-story/scripts/extract-task-diff-stats.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# extract-task-diff-stats.sh — Extract actual git diff stats for a single task
+#
+# Usage: extract-task-diff-stats.sh <task-id>
+#
+# Finds all commits whose message contains <task-id> (EST naming convention,
+# e.g. E32_S06_T01), aggregates the file count and net line delta across all
+# matched commits, and prints:
+#
+#   actual_files_changed: <N>
+#   actual_lines_delta: <N>
+#
+# For bundle tasks (a single commit covers multiple task IDs), each task that
+# matches the commit receives the full bundle stats — this is the "full credit"
+# attribution model. See skills/close-story/SKILL.md for the rationale.
+#
+# Exit codes:
+#   0 — success (even when no commits are found; outputs 0 values)
+#   1 — missing or invalid argument
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Argument validation
+# ---------------------------------------------------------------------------
+
+TASK_ID="${1:-}"
+
+if [[ -z "$TASK_ID" ]]; then
+  echo "Usage: $(basename "$0") <task-id>" >&2
+  echo "  Example: $(basename "$0") E32_S06_T01" >&2
+  exit 1
+fi
+
+# Validate EST format: E##_S##_T##
+if [[ ! "$TASK_ID" =~ ^E[0-9]{2}_S[0-9]{2}_T[0-9]{2}$ ]]; then
+  echo "ERROR: Invalid task ID format '$TASK_ID'. Expected E##_S##_T## (e.g. E32_S06_T01)" >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Find commits matching this task ID in the message
+# ---------------------------------------------------------------------------
+
+MATCHED_SHAS=$(git log --all --no-merges --grep="$TASK_ID" --pretty=format:"%H" 2>/dev/null || true)
+
+if [[ -z "$MATCHED_SHAS" ]]; then
+  # No commits found — task may predate EST tagging or use a non-standard message
+  echo "actual_files_changed: 0"
+  echo "actual_lines_delta: 0"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Aggregate diff stats across all matched commits
+# ---------------------------------------------------------------------------
+
+TOTAL_FILES=0
+TOTAL_INSERTIONS=0
+TOTAL_DELETIONS=0
+
+while IFS= read -r sha; do
+  [[ -z "$sha" ]] && continue
+
+  # Get the diff stat summary line for this commit
+  # git diff --stat <sha>~1..<sha> outputs individual file lines plus a summary:
+  #   N files changed, M insertions(+), K deletions(-)
+  # We only need the last (summary) line.
+  STAT_OUTPUT=$(git diff --stat "${sha}~1..${sha}" 2>/dev/null || true)
+
+  if [[ -z "$STAT_OUTPUT" ]]; then
+    # Commit with no parent (initial commit) or empty diff — skip
+    continue
+  fi
+
+  # Parse files changed from the summary line
+  # The summary line contains "N file(s) changed"
+  FILES_THIS=$(echo "$STAT_OUTPUT" | (grep -o '[0-9][0-9]* file' || true) | awk '{sum+=$1} END {print sum+0}')
+  # Parse insertions
+  INS_THIS=$(echo "$STAT_OUTPUT" | (grep -o '[0-9][0-9]* insertion' || true) | awk '{sum+=$1} END {print sum+0}')
+  # Parse deletions
+  DEL_THIS=$(echo "$STAT_OUTPUT" | (grep -o '[0-9][0-9]* deletion' || true) | awk '{sum+=$1} END {print sum+0}')
+
+  TOTAL_FILES=$((TOTAL_FILES + FILES_THIS))
+  TOTAL_INSERTIONS=$((TOTAL_INSERTIONS + INS_THIS))
+  TOTAL_DELETIONS=$((TOTAL_DELETIONS + DEL_THIS))
+
+done <<< "$MATCHED_SHAS"
+
+TOTAL_DELTA=$((TOTAL_INSERTIONS + TOTAL_DELETIONS))
+
+# ---------------------------------------------------------------------------
+# Output structured results
+# ---------------------------------------------------------------------------
+
+echo "actual_files_changed: $TOTAL_FILES"
+echo "actual_lines_delta: $TOTAL_DELTA"

package/skills/close-story/scripts/update-task-frontmatter.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# update-task-frontmatter.sh — Write or update a YAML key in task/story frontmatter
+#
+# Usage: update-task-frontmatter.sh <file-path> <key> <value>
+#
+# If the key already exists in the frontmatter block (between the first pair
+# of --- delimiters), its value is replaced in-place.
+# If the key does not exist, it is appended just before the closing ---.
+#
+# Works with both GNU and BSD sed (macOS-compatible — uses a temp file instead
+# of sed -i '').
+#
+# Exit codes:
+#   0 — success
+#   1 — argument error or file not found
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Argument validation
+# ---------------------------------------------------------------------------
+
+FILE_PATH="${1:-}"
+KEY="${2:-}"
+VALUE="${3:-}"
+
+if [[ -z "$FILE_PATH" || -z "$KEY" || -z "$VALUE" ]]; then
+  echo "Usage: $(basename "$0") <file-path> <key> <value>" >&2
+  echo "  Example: $(basename "$0") project/board/tasks/E32_S06_T01_my-task.md actual_files_changed 5" >&2
+  exit 1
+fi
+
+if [[ ! -f "$FILE_PATH" ]]; then
+  echo "ERROR: File not found: '$FILE_PATH'" >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Process frontmatter
+# ---------------------------------------------------------------------------
+
+# Strategy:
+#   1. Read the file line by line.
+#   2. Track whether we are inside the frontmatter block (between --- delimiters).
+#   3. If the key exists in frontmatter, replace the line.
+#   4. If we reach the closing --- without having replaced the key, insert the
+#      key:value line immediately before the closing ---.
+#   5. Write the result to a temp file and move it back.
+
+TMPFILE=$(mktemp)
+trap 'rm -f "$TMPFILE"' EXIT
+
+in_frontmatter=0
+frontmatter_open=0   # set to 1 after the opening ---
+key_replaced=0
+closing_found=0
+
+while IFS= read -r line; do
+  # Detect frontmatter boundaries
+  if [[ "$line" == "---" ]]; then
+    if [[ $frontmatter_open -eq 0 ]]; then
+      # Opening ---
+      frontmatter_open=1
+      in_frontmatter=1
+      echo "$line" >> "$TMPFILE"
+      continue
+    elif [[ $in_frontmatter -eq 1 ]]; then
+      # Closing --- — if key was not found yet, insert it now
+      if [[ $key_replaced -eq 0 ]]; then
+        echo "${KEY}: ${VALUE}" >> "$TMPFILE"
+        key_replaced=1
+      fi
+      in_frontmatter=0
+      closing_found=1
+      echo "$line" >> "$TMPFILE"
+      continue
+    fi
+  fi
+
+  # Replace existing key in frontmatter
+  if [[ $in_frontmatter -eq 1 && $key_replaced -eq 0 ]]; then
+    # Match lines starting with exactly this key (not a key that begins with the same prefix)
+    if [[ "$line" =~ ^${KEY}:[[:space:]]* ]]; then
+      echo "${KEY}: ${VALUE}" >> "$TMPFILE"
+      key_replaced=1
+      continue
+    fi
+  fi
+
+  echo "$line" >> "$TMPFILE"
+done < "$FILE_PATH"
+
+# Edge case: file had no frontmatter closing --- (malformed file)
+if [[ $key_replaced -eq 0 && $closing_found -eq 0 ]]; then
+  echo "WARNING: No frontmatter closing --- found in '$FILE_PATH'. Key not written." >&2
+  exit 1
+fi
+
+# Move the temp file into place
+mv "$TMPFILE" "$FILE_PATH"
+trap - EXIT
+
+exit 0

package/skills/commit/SKILL.md

@@ -14,16 +14,43 @@ examples:
 
 # Commit — Commit Completed Work
 
+## Inline Mode (called by /do for inline-scoped tasks)
+
+When invoked with the `--inline` flag OR when the environment variable `JENGA_COMMIT_INLINE=1` is set, execute inline mode:
+
+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:
+   ```
+   task(<E##_S##_T##>): <short description of what was done>
+   ```
+   The task ID (`E##_S##_T##`) must be taken from the context provided by `/do` — do not inspect task frontmatter independently.
+5. **Exit** — do not check for the next epic and do not emit "All Done!" in inline mode. `/do` manages the loop and next-epic detection.
+
+If `--inline` is absent **and** `JENGA_COMMIT_INLINE` is not set (or is not `1`), ignore this section entirely and proceed with normal mode below.
+
+---
+
 ## Instructions
 
 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. **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.)
 
-2. **Commit** using the following format:
+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

@@ -0,0 +1,148 @@
+# 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`, with the `project_files_visibility` field written by `skills/init/scripts/apply-project-visibility.sh` during `/init`; it should not be edited by hand.
+
+---
+
+## Purpose
+
+`jenga.config.json` lives at the root of a consuming project and tracks which version of the JengaAgent framework is currently installed there, where the framework files were placed, and when the last distribution occurred. It is read by the distribution script on subsequent runs to determine the target directory and detect whether an upgrade is needed.
+
+---
+
+## File location
+
+```
+<project-root>/jenga.config.json
+```
+
+---
+
+## Example
+
+```json
+{
+  "project_name": "my-project",
+  "target_dir": ".agents",
+  "version": "2.3.1",
+  "updated_at": "2026-08-11",
+  "last_distributed": "2026-08-11T10:00:00Z",
+  "source": "private",
+  "project_files_visibility": "visible"
+}
+```
+
+---
+
+## Field reference
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `project_name` | string | yes | — | Human-readable identifier for the consuming project. Must match the `name` field of the corresponding entry in the monorepo's `distribute.config.json`. |
+| `target_dir` | string | yes | `.agents` | The directory under the project root where framework files are copied. `distribute-changes.sh` reads this field to resolve the destination path on every run. Change this only if the consuming project uses a non-standard layout. |
+| `version` | string | yes | — | The JengaAgent semantic version currently installed in this project (e.g. `"2.3.1"`). Compared against the `version` field in the monorepo's `package.json` to determine whether an upgrade is required. |
+| `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.
+
+---
+
+## First distribution
+
+When `distribute-changes.sh` runs against a project for the first time and no `jenga.config.json` exists in the project root, the script creates the file from scratch. All six fields are populated using:
+
+- `project_name` — taken from the matching entry in `distribute.config.json`
+- `target_dir` — taken from the matching entry in `distribute.config.json` (falls back to `.agents` if absent)
+- `version` — read from `package.json` in the monorepo at the time of distribution
+- `updated_at` — today's date (`YYYY-MM-DD`)
+- `last_distributed` — current UTC datetime (`YYYY-MM-DDTHH:MM:SSZ`)
+- `source` — hardcoded to `"private"`
+
+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
+
+To prevent a consuming project from reading a partially-written `jenga.config.json` if distribution is interrupted (e.g. by a signal or disk error), the script uses an atomic write pattern:
+
+1. The updated JSON is written to a temporary file in the same directory as the target (e.g. `jenga.config.json.tmp`).
+2. The temporary file is renamed over the target with a single `mv` call.
+
+Because rename is atomic on POSIX filesystems, a reader will always see either the previous complete file or the new complete file — never a half-written intermediate state.
+
+---
+
+## The `active` flag in `distribute.config.json`
+
+`distribute.config.json` (in the monorepo, not in consuming projects) may include an `active` field on each target entry:
+
+```json
+{
+  "targets": [
+    { "name": "my-project", "path": "../my-project", "active": false }
+  ]
+}
+```
+
+- When `active` is `true` (or absent, which defaults to active), the target is distributed normally.
+- When `active` is `false`, distribution is **skipped** for that target and a warning is printed to stdout. The distribution run continues to process remaining targets — an inactive entry is not treated as an error.
+
+Use `active: false` to temporarily pause distribution to a project without removing its entry from the config.