@jenga-ai/agent 3.4.0 → 3.6.0

package/skills/j-gitignore/scripts/untrack-jenga-files.sh

@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+# -----------------------------------------------------------------------------
+# skills/j-gitignore/scripts/untrack-jenga-files.sh
+#
+# Removes Jenga-owned paths from git WITHOUT removing them from disk —
+# `git rm -r --cached`, never a plain `git rm`. The files stay exactly where
+# they are; git simply stops tracking them, and the .gitignore entries written
+# by repair-gitignore.sh then keep them from coming back.
+#
+# Run repair-gitignore.sh FIRST. .gitignore has no effect on an already-tracked
+# file, so untracking without the entries in place just means the next
+# `git add -A` re-adds everything.
+#
+# ─── What "removed from origin" does and does not mean ──────────────────────
+# With --commit --push, these paths disappear from the branch TIP on the
+# remote: clone it fresh and they are gone. Earlier commits are UNTOUCHED —
+# the blobs remain reachable in history, so this is not a secret-scrubbing
+# tool. If something sensitive was committed, treat it as compromised, rotate
+# it, and use a history-rewriting tool (git-filter-repo) separately.
+#
+# Invoked via `bash`, not executed directly.
+#
+# Usage:
+#   untrack-jenga-files.sh [project_root]
+#                          [--tiers scaffold,hybrid,board,optional]
+#                          [--dry-run] [--commit] [--push]
+#                          [--allow-dirty-index]
+#
+# Options:
+#   --dry-run             List what would be untracked; touch nothing.
+#   --commit              Commit the removals. Without it, changes are left
+#                         staged for you to inspect and commit yourself.
+#   --push                Push to the branch's upstream. Requires --commit.
+#                         Never implied — this is the only outward-facing step.
+#   --allow-dirty-index   Proceed even if unrelated changes are already staged.
+#                         Off by default so this can never sweep your staged
+#                         work into its commit.
+#
+# Exit codes:
+#   0  Success (including "nothing tracked — nothing to do")
+#   1  Bad usage or missing prerequisite
+#   2  Invalid tier
+#   3  git operation failed
+#   4  Refused: index already dirty, or --push without --commit
+# -----------------------------------------------------------------------------
+
+set -uo pipefail
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/_catalog.sh"
+
+info() { echo "[untrack] $*"; }
+warn() { echo "[untrack] WARNING: $*"; }
+err()  { echo "[untrack] ERROR: $*" >&2; }
+
+PROJECT_ROOT=""
+TIERS="scaffold"
+DRY_RUN=0
+DO_COMMIT=0
+DO_PUSH=0
+ALLOW_DIRTY=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --tiers)   TIERS="${2:-}"; shift 2 ;;
+    --tiers=*) TIERS="${1#*=}"; shift ;;
+    --dry-run) DRY_RUN=1; shift ;;
+    --commit)  DO_COMMIT=1; shift ;;
+    --push)    DO_PUSH=1; shift ;;
+    --allow-dirty-index) ALLOW_DIRTY=1; shift ;;
+    -h|--help)
+      echo "Usage: $(basename "$0") [project_root] [--tiers <csv>] [--dry-run] [--commit] [--push] [--allow-dirty-index]"
+      exit 0 ;;
+    -*) err "Unknown option: $1"; exit 1 ;;
+    *)
+      if [ -n "$PROJECT_ROOT" ]; then err "More than one project root given."; exit 1; fi
+      PROJECT_ROOT="$1"; shift ;;
+  esac
+done
+
+if [ "$DO_PUSH" -eq 1 ] && [ "$DO_COMMIT" -eq 0 ]; then
+  err "--push requires --commit. There would be nothing to push."
+  exit 4
+fi
+
+PROJECT_ROOT="${PROJECT_ROOT:-$PWD}"
+validate_tiers "$TIERS" || exit 2
+resolve_root "$PROJECT_ROOT" || exit 1
+load_catalog "$TIERS" || exit 1
+
+# ─── Refuse to run on a dirty index ─────────────────────────────────────────
+# .gitignore is the one staged path that is never "unrelated": it is the
+# companion change repair-gitignore.sh just made, and untracking without it is
+# pointless. Staged alone, it is allowed through and folded into this commit.
+# Anything else staged is refused.
+if [ "$ALLOW_DIRTY" -eq 0 ] && [ "$DRY_RUN" -eq 0 ]; then
+  if ! git diff --cached --quiet 2>/dev/null; then
+    staged="$(git diff --cached --name-only)"
+    if [ "$staged" = ".gitignore" ]; then
+      info "Staged .gitignore detected — folding the ignore-rule change into this commit."
+    else
+      err "The index already has staged changes:"
+      printf '%s\n' "$staged" | sed 's/^/        /' >&2
+      err "Refusing to run — a --commit here would sweep them into this commit."
+      err "Commit or unstage them first, or pass --allow-dirty-index if you"
+      err "genuinely want them included."
+      exit 4
+    fi
+  fi
+fi
+
+# ─── Find what is actually tracked ──────────────────────────────────────────
+TRACKED_PATHS=()
+TOTAL_FILES=0
+for i in "${!CATALOG_PATHS[@]}"; do
+  path="${CATALOG_PATHS[$i]}"
+  count="$(git ls-files -- "$path" 2>/dev/null | wc -l | tr -d ' ')"
+  if [ "${count:-0}" -gt 0 ]; then
+    TRACKED_PATHS+=("$path")
+    TOTAL_FILES=$((TOTAL_FILES + count))
+    printf '  %-36s %s tracked file(s)\n' "$path" "$count"
+  fi
+done
+
+if [ "${#TRACKED_PATHS[@]}" -eq 0 ]; then
+  info "No catalog path (tiers: ${TIERS}) is tracked — nothing to untrack."
+  exit 0
+fi
+
+echo
+info "${#TRACKED_PATHS[@]} path(s), ${TOTAL_FILES} file(s) would stop being tracked."
+info "All of them remain on disk — this uses 'git rm -r --cached'."
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  info "--dry-run — nothing changed."
+  exit 0
+fi
+
+# ─── Untrack ────────────────────────────────────────────────────────────────
+for path in "${TRACKED_PATHS[@]}"; do
+  if ! git rm -r --cached --quiet -- "$path"; then
+    err "git rm --cached failed for '${path}'. The index may be partially staged;"
+    err "inspect with 'git status' and 'git reset' to back out."
+    exit 3
+  fi
+  info "Untracked: ${path}"
+done
+
+# Verify nothing was deleted from disk before reporting success.
+MISSING=0
+for path in "${TRACKED_PATHS[@]}"; do
+  probe="${path%/}"
+  if [ ! -e "$probe" ]; then
+    warn "'${probe}' is not on disk. It was already absent before this ran"
+    warn "(git tracked it, the working tree did not), so nothing was lost here."
+    MISSING=$((MISSING + 1))
+  fi
+done
+[ "$MISSING" -eq 0 ] && info "Verified: every untracked path is still present on disk."
+
+if [ "$DO_COMMIT" -eq 0 ]; then
+  echo
+  info "Changes are STAGED but not committed. Review with:"
+  info "    git status"
+  info "    git diff --cached --stat"
+  info "Then commit yourself, or re-run with --commit."
+  exit 0
+fi
+
+# ─── Commit ─────────────────────────────────────────────────────────────────
+COMMIT_MSG="chore(jenga): untrack Jenga-owned files, keep them on disk
+
+Removes the Jenga scaffold from version control via 'git rm --cached' and
+relies on the j.gitignore managed block to keep it out. Files are untouched
+on disk. Tiers: ${TIERS}.
+
+Note: this changes the branch tip only — earlier commits still contain these
+paths."
+
+if ! git commit -q -m "$COMMIT_MSG"; then
+  err "git commit failed. Your removals are still staged."
+  exit 3
+fi
+info "Committed: $(git rev-parse --short HEAD)"
+
+if [ "$DO_PUSH" -eq 0 ]; then
+  echo
+  info "Not pushed. The remote still has these files until you push."
+  exit 0
+fi
+
+# ─── Push ───────────────────────────────────────────────────────────────────
+BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+UPSTREAM="$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null)"
+
+if [ -z "$UPSTREAM" ]; then
+  err "Branch '${BRANCH}' has no upstream — refusing to guess a remote."
+  err "Set one, then push yourself:  git push -u origin ${BRANCH}"
+  err "The commit itself succeeded and is safe on your local branch."
+  exit 3
+fi
+
+info "Pushing ${BRANCH} → ${UPSTREAM} ..."
+if ! git push; then
+  err "Push failed — most likely the branch is behind its upstream."
+  err "Reconcile (git pull --rebase) and push yourself. The commit is safe locally."
+  exit 3
+fi
+
+info "Pushed. These paths are gone from ${UPSTREAM}'s tip."
+info "They REMAIN in earlier commits — this did not rewrite history."
+exit 0

package/skills/j-idea/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: j.idea
-description: Polyfill alias of the idea skill under a collision-safe directory name. Identical behavior to /idea — Capture a loosely-defined idea to project/ideas.md — a lightweight, "maybe someday" log with no board or promotion overhead. Use when the bare /idea form is shadowed by another tool's own built-in command of the same name.
+description: Polyfill alias of the idea skill under a collision-safe directory name. Identical behavior to /idea — DEPRECATED - use the prefixed 'j-idea' skill instead. Capture a loosely-defined idea to project/ideas.md — a lightweight, "maybe someday" log with no board or promotion overhead. Use when the bare /idea form is shadowed by another tool's own built-in command of the same name.
 keywords:
   - idea
   - capture idea
@@ -52,12 +52,84 @@ This file is generated/synced by `scripts/generate-j-alias.sh idea` from `skills
 - **Promoting an idea** means re-running `/brainstorm` on it, which routes onward to `/btw` or `/todo` as normal. That routing behavior already exists and is out of scope for `/idea`.
 - **Terminal idea states** are marked directly in `project/ideas.md` using the same HTML-comment tag convention `project/todo.md` uses for `RECONCILED`:
   - `PROMOTED` — the idea was picked up via `/brainstorm` and turned into board work.
-  - `DISCARDED` — the idea was reviewed and dropped.
+  - `REJECTED` — the idea was reviewed and dropped.
 
-  Example (mirroring `project/todo.md`'s tagging style):
+### Embedded Board ID
+
+`PROMOTED`/`REJECTED` tags support an embedded board ID, so the idea→board-item link is
+machine-readable directly from the tag itself, without needing a separate lookup:
+
+- `<!-- PROMOTED: E##_S##[_T##] -->` — the `_T##` task suffix is optional; use whichever level
+  the idea was actually promoted into (an epic, a story, or a specific task).
+- `<!-- REJECTED -->` — stays bare, with no embedded ID. A rejection has no resulting board
+  item to point at.
+
+Example (mirroring `project/todo.md`'s tagging style):
+```
+Add dark mode toggle to settings page <!-- PROMOTED: E12_S03 -->
+Add a settings-page keyboard shortcut cheat sheet <!-- PROMOTED: E12_S03_T02 -->
+Rewrite onboarding copy in a more casual tone <!-- REJECTED -->
+```
+
+### Source-Rapport Link Convention
+
+Some ideas originate from a rapport rather than being manually captured via `/idea` — e.g. when
+scrum-master's `rapport_review` step (E35_S03) detects a distinct idea surfaced inside a
+problem rapport and, on user confirmation, appends it to `project/ideas.md` the same way
+`/idea` does. When that happens, the entry's source rapport is recorded with a second inline
+HTML comment on the same line:
+
+```
+<!-- rapport: <path/to/rapport.md> -->
+```
+
+Rules:
+- Written at capture time, alongside the idea text, by whichever flow is adding the entry
+  (scrum-master's rapport-derived capture path; `/idea`'s own manual capture never has a source
+  rapport and omits this comment entirely).
+- Left in place through promotion/rejection — the `rapport:` comment and the terminal
+  `PROMOTED`/`REJECTED` comment coexist on the same line, e.g.:
   ```
-  Add dark mode toggle to settings page <!-- PROMOTED -->
-  Rewrite onboarding copy in a more casual tone <!-- DISCARDED -->
+  Extract shared retry logic into a utility <!-- rapport: project/rapports/problems/E40_S02_T01-segment-remarks.md --> <!-- PROMOTED: E61_S01 -->
   ```
+- Consumed by the outcome-record mechanism at promotion/rejection time: if a `rapport:` comment
+  is present on the line, that rapport is updated with the decision (and `[SPIKE]`-prefixed in
+  its title/header if not already, per `templates/SCRUM_BOARD_SCHEMA.md`'s `[SPIKE]` section);
+  if absent (a manually-captured `/idea` entry with no source rapport), a
+  `project/documentation/plans/<slug>_PROMOTED.md` or `_REJECTED.md` file is created instead.
+- Verified compatible with `scripts/idea_manager.sh`'s `real_entries()` filtering: that function
+  only strips lines whose first non-whitespace characters are `<!--`; a trailing inline comment
+  on an otherwise real entry line is untouched and the line still counts as a real entry.
+
+No agent invoked by `/idea` applies terminal (`PROMOTED`/`REJECTED`) tags or acts on them — that
+is reserved for the promotion step (e.g. within `/brainstorm`) and, for rapport-sourced ideas,
+scrum-master's rapport-review flow.
+
+### Outcome-Record Mechanism (`idea_manager.sh`) — E35_S03_T03
+
+`scripts/idea_manager.sh` implements the tagging and outcome-record behavior described above, via
+four additional subcommands beyond `add`/`list`:
+
+- `tag "<idea-text>" <PROMOTED:E##_S##[_T##]|REJECTED>` — writes the terminal tag onto the
+  `project/ideas.md` line matching `<idea-text>` (an exact/literal match; errors if zero or more
+  than one line matches, and errors if the line is already tagged).
+- `get-id "<idea-text>"` — prints the embedded board ID from that line's `PROMOTED` tag (errors
+  if the line has no `PROMOTED` tag).
+- `get-rapport "<idea-text>"` — prints the `rapport:` path recorded on that line, or nothing
+  (exit 0) if the line has no source-rapport comment.
+- `resolve "<idea-text>" <promoted|rejected> [board_id]` — the full outcome-record mechanism in
+  one call: tags the line (as `tag` does), then either updates the idea's source rapport or, if
+  none is recorded, creates the `project/documentation/plans/` fallback file:
+  - **Source rapport present:** the rapport's `# Rapport: ...` title line is prefixed
+    `[SPIKE] ` if not already, and an `## Idea Outcome Record` section (decision, date, resulting
+    board ID if promoted, and the idea text) is appended to the rapport file.
+  - **No source rapport:** `project/documentation/plans/<slug>_PROMOTED.md` or `_REJECTED.md` is
+    created (idea text slugified, lowercased, capped at 60 characters), containing the same
+    decision/date/board-ID/idea-text content.
+
+  `board_id` is required for `promoted` (validated to start with `E<digits>`) and must be omitted
+  for `rejected` (a rejection has no resulting board item).
 
-No agent invoked by `/idea` applies these tags or acts on them — that is reserved for a future promotion step (e.g. within `/brainstorm`).
+This is the mechanism itself, not the trigger — nothing currently calls `resolve` automatically.
+A future promotion step (e.g. within `/brainstorm`'s routing, or scrum-master acting on a
+rapport-sourced idea) is expected to invoke it once that trigger exists.

package/skills/j-idea/assets/idea_template.md

@@ -1,3 +1,3 @@
 # Ideas
 
-<!-- Format: <idea text> (one line per idea; terminal tags PROMOTED / DISCARDED appended by /brainstorm, not by /idea) -->
+<!-- Format: <idea text> (one line per idea; terminal tags PROMOTED / REJECTED appended by /brainstorm, not by /idea) -->

package/skills/j-improve/SKILL.md

@@ -50,7 +50,7 @@ Assess whether you have enough context to evaluate current behavior against the
 Invoke the `/examplify` skill. Specify clearly what you want it to find out — e.g. which code paths are exercised, what inputs/outputs look like, or what edge cases exist.
 
 ### 5. Run `/evaluate`
-Copy `.agents/skills/evaluate/assets/evaluation_invokation_template.yml` and fill in:
+Copy `.agents/skills/j-evaluate/assets/evaluation_invokation_template.yml` and fill in:
 - `paths`: path(s) to the relevant example files
 - `goal`: the confirmed target goal
 

package/skills/j-init/SKILL.md

@@ -101,13 +101,44 @@ run can never silently relocate directories or edit `.gitignore`.
 > `.agents/`/`.claude/` convention), was built and then withdrawn before release —
 > testing found it left board resolution and session-end hooks writing to two
 > different trees. It is not offered here. See
-> `skills/distribute/CONFIG_SCHEMA.md` for the root-cause note and the tracked
+> `skills/j-distribute/CONFIG_SCHEMA.md` for the root-cause note and the tracked
 > follow-up to reintroduce it once fixed.
 
-Carry the chosen value into step 3. Do not apply it yourself — the script owns all
+Carry the chosen value into step 4. Do not apply it yourself — the script owns all
 of the mechanical work.
 
-### 3. Run the scaffold script
+### 3. Ask whether the distributed scaffold should be committed
+
+This is a **distinct** question from step 2 — `project_files_visibility` (step 2)
+covers only the `project/` working tree (the scrum board, `todo.md`, `queue/`,
+`rapports/`, `logs/`). It has no effect on `.claude/`/`.agents/`, the distributed
+framework scaffold (skill and agent definitions), which is a separate tree with a
+separate lifecycle — it gets overwritten wholesale by every `/distribute` run or npm
+upgrade, unlike `project/`. Kept as its own flag (`scaffold_visibility`) rather than
+folded into `project_files_visibility`'s enum; see
+`skills/j-distribute/CONFIG_SCHEMA.md`'s "Scaffold visibility" section for the full
+rationale.
+
+Ask the user this question, verbatim, before running any script:
+
+    Should the distributed .claude/.agents Jenga AI framework scaffold (skills, agent
+    definitions — implementation detail, not your own code) be committed into this
+    project's git history?
+    1. Yes, commit it — keep it tracked and visible, exactly like today
+    2. No, keep it on disk but add it to .gitignore so it's never committed
+    3. Not sure — explain the trade-offs and ask me again
+
+If the user picks option 3, explain the trade-offs and re-ask. Do not proceed until
+the answer maps to one of `visible` (option 1) or `ignored` (option 2).
+
+If the run is non-interactive (no user available to answer), use the default:
+**`visible`**. It is the only choice that changes nothing on disk, so an unattended
+run reproduces exactly today's behavior — the scaffold is still committed by default.
+
+Carry the chosen value into step 4 as well. Do not apply it yourself — the script
+owns all of the mechanical work.
+
+### 4. Run the scaffold script
 
 `init.sh` is not guaranteed to live at a single fixed path: in a project that
 installed Jenga via npm, it was mirrored to `.claude/skills/j-init/scripts/`
@@ -117,7 +148,7 @@ source checkout, where it lives at the bare `skills/j-init/scripts/` path
 instead. This step runs before `CLAUDE.md`/`AGENTS.md` exist, so it cannot
 rely on either file's routing instructions to resolve the path — it must
 locate its own script directly. Execute the init script from the project
-root, passing the choice from step 2:
+root, passing the choices from steps 2 and 3:
 
 ```bash
 INIT_SCRIPT=""
@@ -128,11 +159,14 @@ if [[ -z "$INIT_SCRIPT" ]]; then
   echo "Error: could not locate init.sh under .claude/skills/, .agents/skills/, or skills/" >&2
   exit 1
 fi
-chmod +x "$INIT_SCRIPT" && "$INIT_SCRIPT" --visibility <visible|ignored>
+chmod +x "$INIT_SCRIPT" && "$INIT_SCRIPT" --visibility <visible|ignored> --scaffold-visibility <visible|ignored>
 ```
 
 Omitting `--visibility` falls back to the `JENGA_PROJECT_FILES_VISIBILITY`
-environment variable, then to `visible`.
+environment variable, then to `visible`. Omitting `--scaffold-visibility` falls
+back to the `JENGA_SCAFFOLD_VISIBILITY` environment variable, then to `visible`
+— the same default-preserving fallback chain, applied independently to the
+distributed-scaffold question from step 3.
 
 This script handles all scaffolding in one step:
 1. Initializes the git repository
@@ -148,22 +182,27 @@ This script handles all scaffolding in one step:
 11. Creates `docs/STRATEGY.md` — a strategic brief stub intended for investors, partners, and the product team
 12. Creates `CHANGELOG.md` from the shared template — a running log of notable changes, seeded with an `[Unreleased]` section
 13. Applies the chosen visibility mode via `scripts/apply-project-visibility.sh`, which records it as `project_files_visibility` in `jenga.config.json` and performs any `.gitignore` change
-14. Stages and commits all files with the message `init: scaffold project structure and workflow config`
+14. Applies the chosen scaffold visibility mode via `scripts/apply-scaffold-visibility.sh`, which records it as `scaffold_visibility` in `jenga.config.json` and, when `ignored`, adds `.claude/` and `.agents/` to `.gitignore`
+15. Stages and commits all files with the message `init: scaffold project structure and workflow config`
 
-The visibility mode is validated before any scaffolding happens, so an invalid
-value fails fast and leaves nothing behind. It is applied before the commit, so
-the `.gitignore` entry is captured in the initial commit.
+Both visibility modes are validated before any scaffolding happens, so an invalid
+value fails fast and leaves nothing behind. Both are applied before the commit, so
+any resulting `.gitignore` entries are captured in the initial commit — this is what
+lets `scaffold_visibility: ignored` keep `.claude/`/`.agents/` out of the commit even
+though they may already exist on disk (from npm postinstall or a prior `/distribute`
+run) by the time `/init` runs `git add -A`.
 
 If the script fails, check that you are in the project root and that git and `jq`
 are available.
 
-See `skills/distribute/CONFIG_SCHEMA.md` for the full `project_files_visibility`
-field reference.
+See `skills/j-distribute/CONFIG_SCHEMA.md` for the full `project_files_visibility` and
+`scaffold_visibility` field reference.
 
-### 4. Prompt next step
+### 5. Prompt next step
 
 Inform the user that setup is complete, and state which visibility mode was applied
-and where the working files now live. Mention that `docs/STRATEGY.md` was created as
+for both `project_files_visibility` and `scaffold_visibility`, and where the working
+files and scaffold now live. Mention that `docs/STRATEGY.md` was created as
 a strategic brief stub for investors, partners, and the product team — they can fill
 it in now or return to it later. Suggest running `/pi-plan` to define project goals
 and epics.

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

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

package/skills/j-init/assets/scope-thresholds_template.json

@@ -1,7 +1,10 @@
 {
-  "threshold_version": 2,
+  "threshold_version": 3,
   "inline_max_files": 3,
   "inline_max_lines": 75,
   "story_max_files": 5,
-  "bundle_lock_ttl_minutes": 30
+  "bundle_lock_ttl_minutes": 30,
+  "max_concurrent_developers": 3,
+  "max_concurrent_testers": 3,
+  "slot_ttl_minutes": 45
 }

package/skills/j-init/scripts/apply-scaffold-visibility.sh

@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+#
+# apply-scaffold-visibility.sh — apply the `scaffold_visibility` mode to a project.
+#
+# This is a DISTINCT flag from `project_files_visibility` (see
+# apply-project-visibility.sh). `project_files_visibility` covers the
+# project/ working tree (scrum board, todo.md, queue/, rapports/, logs/) —
+# E31_S05's own Background section scopes it to that tree only. This script
+# instead covers the *distributed framework scaffold* — `.claude/` and
+# `.agents/` — which is a different tree with a different lifecycle (it is
+# overwritten wholesale by every `/distribute` run or npm upgrade; project/
+# is not). Filed as new, adjacent scope under E31_S07 rather than folded
+# silently into project_files_visibility's existing enum. See
+# skills/j-distribute/CONFIG_SCHEMA.md's "Scaffold visibility" section for the
+# full rationale.
+#
+# This is skills/j-init/'s own copy of skills/init/scripts/apply-scaffold-visibility.sh
+# (E31_S07_T03) — skills/j-init/ is a separate, hand-maintained directory, not
+# auto-synced with skills/init/ (scripts/generate-j-alias.sh explicitly excludes
+# this pair), and is the copy that actually ships to public-GitHub-mirror and
+# npm-package consumers. Keep this file's logic in lockstep with skills/init/'s
+# copy — any behavioral change made there should be mirrored here.
+#
+# Usage:
+#   apply-scaffold-visibility.sh <mode> [project_root]
+#   apply-scaffold-visibility.sh --check-only <mode>
+#
+# Modes:
+#   visible   Scaffold directories stay where they are. No-op on disk beyond
+#             the config write. This is the default — matches the behavior
+#             of every /init run before this flag existed.
+#   ignored   .claude/ and .agents/ are added to the project's .gitignore —
+#             present on disk (whenever npm postinstall or /distribute
+#             places them, whether that happens before or after this runs),
+#             never committed. Entries are written unconditionally, the same
+#             way apply-project-visibility.sh gitignores project/ whether or
+#             not it exists yet, so a scaffold created by a later
+#             /distribute run is covered too, not just one already on disk.
+#
+# Exit codes:
+#   0  Success
+#   1  Bad usage or missing prerequisite
+#   2  Invalid mode (outside the two-value enum)
+#   3  Filesystem apply failure
+#   4  jenga.config.json write failure
+
+# Do NOT use set -e globally — each step handles its own errors.
+set -uo pipefail
+
+info() { echo "[scaffold-visibility] $*"; }
+warn() { echo "[scaffold-visibility] WARNING: $*"; }
+err()  { echo "[scaffold-visibility] ERROR: $*" >&2; }
+
+usage() {
+  echo "Usage: $(basename "$0") <visible|ignored> [project_root]" >&2
+  echo "       $(basename "$0") --check-only <visible|ignored>" >&2
+  exit 1
+}
+
+# The distributed framework scaffold — mirrored copies of skills/agents for
+# Claude Code and Copilot/other agents. Distinct from JENGA_WORKING_PATHS in
+# apply-project-visibility.sh, which covers project/ only.
+JENGA_SCAFFOLD_PATHS=(".claude" ".agents")
+
+VALID_MODES="visible ignored"
+
+validate_mode() {
+  local mode="$1"
+  for valid in $VALID_MODES; do
+    [ "$mode" = "$valid" ] && return 0
+  done
+  err "Invalid scaffold_visibility value: '${mode}'"
+  err "Allowed values are: ${VALID_MODES// /, }"
+  exit 2
+}
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+CHECK_ONLY=0
+if [ "${1:-}" = "--check-only" ]; then
+  CHECK_ONLY=1
+  shift
+fi
+
+MODE="${1:-}"
+[ -n "$MODE" ] || usage
+
+validate_mode "$MODE"
+
+if [ "$CHECK_ONLY" -eq 1 ]; then
+  info "Mode '$MODE' is valid."
+  exit 0
+fi
+
+PROJECT_ROOT="${2:-$PWD}"
+if [ ! -d "$PROJECT_ROOT" ]; then
+  err "Project root does not exist: $PROJECT_ROOT"
+  exit 1
+fi
+cd "$PROJECT_ROOT" || { err "Cannot enter project root: $PROJECT_ROOT"; exit 1; }
+
+if ! command -v jq >/dev/null 2>&1; then
+  err "jq is required to write jenga.config.json but was not found on PATH."
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# ignored — append to .gitignore, without ever duplicating an entry
+# ---------------------------------------------------------------------------
+
+gitignore_append() {
+  local entry="$1"
+  local gitignore=".gitignore"
+
+  if [ -f "$gitignore" ] && grep -qxF -- "$entry" "$gitignore"; then
+    info "'$entry' already present in .gitignore — skipping."
+    return 0
+  fi
+
+  # Don't glue our entry onto a final line that lacks a newline.
+  if [ -s "$gitignore" ] && [ -n "$(tail -c 1 "$gitignore")" ]; then
+    printf '\n' >> "$gitignore"
+  fi
+
+  if ! printf '%s\n' "$entry" >> "$gitignore"; then
+    err "Failed to append '$entry' to .gitignore"
+    exit 3
+  fi
+  info "Added '$entry' to .gitignore"
+}
+
+# ---------------------------------------------------------------------------
+# jenga.config.json — merge the field in, written atomically (temp + mv)
+# ---------------------------------------------------------------------------
+
+write_scaffold_config() {
+  local mode="$1"
+  local config="jenga.config.json"
+  local tmp="${config}.tmp"
+  local existing='{}'
+
+  # /init normally runs before any /distribute, so the file usually does not
+  # exist yet. Merge rather than overwrite so other fields survive.
+  if [ -f "$config" ]; then
+    if ! jq empty "$config" 2>/dev/null; then
+      err "$config exists but contains malformed JSON — refusing to overwrite it."
+      exit 4
+    fi
+    existing="$(cat "$config")"
+  fi
+
+  local content
+  content="$(jq --arg v "$mode" '.scaffold_visibility = $v' <<< "$existing")"
+  if [ -z "$content" ]; then
+    err "Failed to construct $config content."
+    exit 4
+  fi
+
+  if ! printf '%s\n' "$content" > "$tmp"; then
+    err "Failed to write temporary config file: $tmp"
+    exit 4
+  fi
+
+  if ! mv "$tmp" "$config"; then
+    err "Failed to atomically move $tmp to $config"
+    rm -f "$tmp"
+    exit 4
+  fi
+
+  info "Wrote scaffold_visibility = \"$mode\" to $config"
+}
+
+# ---------------------------------------------------------------------------
+# Apply
+# ---------------------------------------------------------------------------
+
+case "$MODE" in
+  visible)
+    info "Mode 'visible' — scaffold directories stay in place; nothing to change on disk."
+    ;;
+  ignored)
+    for path in "${JENGA_SCAFFOLD_PATHS[@]}"; do
+      gitignore_append "${path}/"
+    done
+    ;;
+esac
+
+write_scaffold_config "$MODE"
+
+info "Applied scaffold_visibility '$MODE' to $PROJECT_ROOT"