@jenga-ai/agent 1.1.0 → 1.2.0

package/skills/do/SKILL.md

@@ -304,7 +304,7 @@ Before starting:
 Before invoking the developer, check whether this task was manually scoped by a human operator.
 
 1. Read `jenga_assigned` from the resolved task's frontmatter.
-2. If `jenga_assigned` is `true` or the field is absent — proceed to step 5 without any further check.
+2. If `jenga_assigned` is `true` or the field is absent — proceed to step 4.2 without any further check.
 3. If `jenga_assigned` is `false`:
    a. Read `override_justification` from the task's frontmatter.
    b. If `override_justification` is absent or its value is an empty string, **halt execution** and emit:
@@ -316,21 +316,58 @@ Before invoking the developer, check whether this task was manually scoped by a
       ```
       Override acknowledged for <task_id>: <override_justification>
       ```
-      Then proceed to step 5.
+      Then proceed to step 4.2.
 
 ### 4.2. Inline Execution Path (execution_scope: inline)
 
-If the resolved task has `execution_scope: inline` in its frontmatter, execute the task directly in the current session without spawning a developer subagent:
+After resolving the task context (step 4) and passing override validation (step 4.1), read `execution_scope` from the task frontmatter.
 
-1. Read the task file and load its full content (description, acceptance criteria).
+**Locked-task dispatch guard (defense-in-depth).** Before branching on `execution_scope` below, read `crucial_level` from the task frontmatter (per `templates/SCRUM_BOARD_SCHEMA.md`'s Crucial Flag Fields). If `crucial_level: locked`:
+
+- This task MUST be routed through the inline execution path below — no worktree, no developer subagent — regardless of what `execution_scope` currently reads. This guards against a locked task reaching dispatch with a non-`inline` `execution_scope` (a race, a manually edited file, or a task added to a story's `tasks:` list after `skills/jenga/SKILL.md` Phase 0.5's Rule 4 last ran).
+- If `execution_scope` is already `inline`, proceed directly to the inline steps below — no correction needed.
+- If `execution_scope` is anything other than `inline` (absent, `task`, `story`, or `epic`), auto-correct it to `inline` in the task frontmatter now, and record the correction using the **same logged-note convention** as `skills/jenga/SKILL.md` Phase 0.5 Rule 4 (do not invent a second, inconsistent logging mechanism):
+  - Append to the task's `override_justification` frontmatter field:
+    ```
+    override_justification: "/do dispatch guard auto-correction <date>: execution_scope forced from '<previous_value>' to 'inline' because crucial_level: locked."
+    ```
+  - Then emit (non-fatally — do not halt):
+    ```
+    AUTO-CORRECTION [<task_id>]: crucial_level=locked requires execution_scope=inline; corrected from "<previous_value>" to "inline".
+    ```
+  - Then proceed to the inline steps below with the now-corrected `execution_scope: inline`.
+- **Under no circumstance does a `crucial_level: locked` task fall through to step 5** (developer agent invocation / worktree creation) — this applies whether the task was resolved individually or would otherwise have entered the normal per-task worktree-creation flow.
+
+**If `execution_scope: inline`** (including tasks corrected above), execute the task directly in the current session without spawning a developer subagent:
+
+1. Read the task file and load its full content (description, acceptance criteria). Do NOT create a worktree. Do NOT spawn a developer subagent.
 2. Implement the task inline — make the required changes to files directly in the current session.
-3. Commit the changes using the standard commit convention (`task(<task_id>): <short description>`).
-4. Run the **Intent-vs-Diff Check** (see `### 5.1. Intent-vs-Diff Check` below) for this task.
-5. Self-verify the implementation against the acceptance criteria.
-6. Write `status: Passed` and `date_completed: <today>` to the task's frontmatter if verification passes.
-7. Continue to step 6 (documentation verification) and then step 7 (post-completion).
+3. Run the smoke test harness before committing anything:
+   - Run `bash scripts/smoke-harness.sh <changed_file>...`, passing the paths changed in step 2. With no arguments the harness infers them from `git diff --name-only HEAD`. It exits `0` on pass and `1` on failure.
+   - If `scripts/smoke-harness.sh` does not exist, log a warning and treat the result as a pass:
+     ```
+     WARNING [<task_id>]: scripts/smoke-harness.sh not found. Smoke test skipped (stub pass).
+     ```
+4. **If the smoke test exits non-zero**:
+   - Write `status: Failed` to the task's frontmatter.
+   - Emit:
+     ```
+     INLINE TASK FAILED [<task_id>]: smoke test returned non-zero exit code. Task marked Failed. Halting.
+     ```
+   - Do not commit. Do not proceed to the next task.
+5. **If the smoke test passes**:
+   - Commit the changes using the standard commit convention (`task(<task_id>): <short description>`) via `/commit` in inline mode (E32_S04_T03).
+   - Run the **Intent-vs-Diff Check** (see `### 5.1. Intent-vs-Diff Check` below) for this task.
+   - Self-verify the implementation against the acceptance criteria.
+   - Write `status: Passed` and `date_completed: <today>` to the task's frontmatter if verification passes.
+   - Remove the task from `project/todo.md`.
+6. `inline` tasks do not invoke the tester agent — the smoke test and self-verification are the only gates.
+7. `inline` tasks always have `needs_docs: false` — skip plan and summary documentation for the implemented task.
+8. Continue to `### 6. Verify documentation`, then `### 7. After successful completion`.
+
+If the implementation cannot be completed inline (scope is larger than anticipated), abort and re-route to the normal developer path (step 5) — unless `crucial_level: locked`, in which case do not re-route; re-attempt inline or halt and report, per the locked-task dispatch guard above.
 
-If the implementation cannot be completed inline (scope is larger than anticipated), abort and re-route to the normal developer path (step 5).
+**If `execution_scope` is not `inline`** (or is absent / `task` / `story` / `epic`) **and `crucial_level` is not `locked`**, proceed to step 5 (invoke the developer agent) as normal.
 
 ### 5. Invoke the developer agent
 Pass the following to the developer agent:
@@ -392,7 +429,7 @@ If either file is missing, ask the developer to produce it before continuing.
 Additionally, if the completed work introduces user-facing changes, update `README.md` and `WARP.md` accordingly.
 
 ### 7. After successful completion
-- Check for any `_INSTRUCTIONS.md` files in `$(bash scripts/board_resolver.sh)tasks/` whose ID matches the completed task. If found, present them to the user and explain that these actions must be completed before the feature will work correctly.
+- Check for any `_INSTRUCTIONS.md` files in `project/instructions/` whose ID matches the completed task. If found, present them to the user and explain that these actions must be completed before the feature will work correctly.
 - Invoke the `/commit` skill to commit the work (if not already committed by the developer)
 - Run `bash scripts/todo_manager.sh remove '<task title>'` to remove the completed task from `project/todo.md`
 - Run `bash scripts/todo_manager.sh teardown` to delete `project/todo.md` if it is now effectively empty

package/skills/doc-sync/SKILL.md

@@ -87,6 +87,21 @@ For each update target and its resolved sources:
    - Outdated examples, wrong flag names, stale code snippets.
    - Incorrect or missing configuration keys/values.
 
+#### 4a. Cross-reference `.publicignore` for "missing documentation" candidates
+
+Every candidate identified above as "missing documentation for new things added in source" ships publicly by default unless this project has adopted `/mirror-public`. Before flagging any such candidate, check whether it's actually private-only:
+
+1. **Check for `.publicignore` at the repo root.** Most projects using this framework will not have one (they haven't adopted `/mirror-public`) — if it's absent, **skip this entire sub-step**. Fall through to flagging every "missing documentation" candidate exactly as `3.` above already would, with no further filtering.
+2. **If `.publicignore` exists**, for each "missing documentation" candidate, determine its source path (relative to the repo root) and classify it by running:
+   ```
+   scripts/check-publicignore-match.sh <path> [<path> ...]
+   ```
+   This reuses `/mirror-public`'s own `mirror.sh` matching logic (`rsync --exclude-from=.publicignore`) — a file this script reports `BLOCKED` is guaranteed to be a file `/mirror-public --dry-run` would also report as "would be blocked", and vice versa for `PUBLIC`. It needs no network access and does not require `/mirror-public` to be configured.
+3. **`BLOCKED`** → do not flag this candidate as missing documentation. It's private-only and will never ship to the public mirror, so public docs coverage is not applicable.
+4. **`PUBLIC`** → flag it as usual in step 5's report, and name `README.md` and `project/.wiki/documentation.md` (the confirmed canonical full-reference doc — see `assets/doc_targets.md`) as the target docs to check for coverage of this item.
+
+This sub-step only changes what gets flagged as "missing documentation" in step 3's third bullet — it does not affect the other three drift categories (renamed/removed references, outdated examples, incorrect config keys), which are flagged regardless of `.publicignore` since they concern existing documentation content, not public-shipping coverage of new source additions.
+
 ### 5. Report findings before updating
 
 Before making any writes, present a concise drift summary per file:
@@ -165,3 +180,4 @@ If minification could not reach the target, note: `⚠️ docs/API.md reduced to
 
 - `assets/doc_targets.md` — Editable list of documentation files this skill checks by default.
 - `assets/default_excludes.txt` — Paths always excluded from source analysis unless overridden.
+- `scripts/check-publicignore-match.sh` (repo root) — Used in step 4a to classify "missing documentation" candidates as `PUBLIC`/`BLOCKED` per `.publicignore`, reusing `/mirror-public`'s exact matching semantics.

package/skills/doc-sync/assets/doc_targets.md

@@ -8,7 +8,18 @@ Add one path per line inside the list below. Blank lines and lines starting with
 
 <!-- Add your project's documentation files here, one per line -->
 README.md
+project/.wiki/documentation.md
 <!-- docs/API.md -->
 <!-- docs/config.md -->
 <!-- CHANGELOG.md -->
 <!-- CONTRIBUTING.md -->
+
+<!--
+Note: project/.wiki/documentation.md is the confirmed-canonical full
+skill-reference doc (README.md links to it directly as "Full reference").
+A near-duplicate, project/documentation/documentation.md, has independently
+diverged from this canonical copy — see E28_S03_T01's execution summary for
+the investigation, and story E38_S01 for the planned consolidation. Do not
+add project/documentation/documentation.md here until that consolidation
+lands.
+-->

package/skills/idea/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: idea
+description: Capture a loosely-defined idea to project/ideas.md — a lightweight, "maybe someday" log with no board or promotion overhead.
+keywords:
+  - idea
+  - capture idea
+  - log idea
+  - brain dump
+  - maybe someday
+examples:
+  - "capture this as an idea"
+  - "log this idea for later"
+  - "I have a rough idea I want to jot down"
+metadata:
+  prefered_agent: scrum-master
+---
+
+# Idea — Lightweight Idea Capture
+
+## Instructions
+
+1. **Ensure `project/ideas.md` exists** — If it doesn't exist, it will be auto-created by `idea_manager.sh` from `skills/idea/assets/idea_template.md` — no manual action needed.
+
+2. **Ask the user about the idea:**
+   - What's the idea?
+   - Any known context worth noting (why it came up, what it might relate to)?
+
+   Keep this light — `/idea` is a low-overhead capture, not a structured mission intake like `/todo`.
+
+3. **Add to `project/ideas.md`** by running:
+   ```
+   bash scripts/idea_manager.sh add '<idea>'
+   ```
+
+4. **Ask the user**: "Capture another idea, or done?"
+   - If **another** — go back to step 2.
+   - If **done** — exit.
+
+   Unlike `/todo`, `/idea` never offers to execute, refine, or promote the captured idea(s) at the end. There is no `/do`-style follow-up here — `/idea` has no refine or promotion logic of its own.
+
+## For Reference Only — Promotion Convention (not implemented here)
+
+`/idea` does not implement any refine or promotion mechanism. This section documents, for reference, how promotion is expected to work elsewhere so future flows stay consistent:
+
+- **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.
+
+  Example (mirroring `project/todo.md`'s tagging style):
+  ```
+  Add dark mode toggle to settings page <!-- PROMOTED -->
+  Rewrite onboarding copy in a more casual tone <!-- DISCARDED -->
+  ```
+
+No agent invoked by `/idea` applies these tags or acts on them — that is reserved for a future promotion step (e.g. within `/brainstorm`).

package/skills/idea/assets/idea_handoff_template.md

@@ -0,0 +1,26 @@
+# Idea Handoff
+
+<!-- PREAMBLE (for /idea): This template was pre-filled by a caller (e.g. /spinoff).
+     Skip any questions whose answers are already provided below. Only prompt the user
+     for fields that remain empty or marked as a placeholder. -->
+
+<!-- Format: <mission title>: <E##_S##> (epic/story ref optional) -->
+
+## Mission Title
+<!-- PLACEHOLDER: short name for this idea, e.g. "Refactor auth middleware" -->
+
+## Goal / Objective
+<!-- PLACEHOLDER: what this idea is trying to achieve -->
+
+## Affected Files or Scope
+<!-- PLACEHOLDER: which files, modules, or areas are involved, e.g. src/auth/, skills/idea/ -->
+
+## Intended Approach
+<!-- PLACEHOLDER: step-by-step or high-level approach to the work -->
+
+## Epic / Story Linkage
+<!-- PLACEHOLDER: known Epic or Story ID this links to, e.g. E02_S03 — or "None" if not linked -->
+
+## Origin
+<!-- PLACEHOLDER: EST id (task/story/epic) in progress when the divergence happened, or "None" -->
+<!-- PLACEHOLDER: one-line summary of what the user was doing at the time -->

package/skills/idea/assets/idea_template.md

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

package/skills/init/SKILL.md

@@ -18,14 +18,93 @@ examples:
 
 Follow these steps in order. Do not skip steps — the sequence matters.
 
-### 1–9. Run the scaffold script
+### 1. Detect existing project state
 
-Execute the init script from the project root:
+Before asking anything or scaffolding anything, classify the target directory
+(the current directory) by running the detection script:
 
 ```bash
-chmod +x ./scripts/init.sh && ./scripts/init.sh
+skills/init/scripts/detect-existing-codebase.sh .
 ```
 
+It prints exactly one verdict on stdout:
+
+| Verdict | Meaning | What to do |
+|---|---|---|
+| `empty` | The directory is empty, or contains only `.git`, `.gitignore`, and top-level `README*`/`LICENSE*` boilerplate. | Proceed to step 2 — behaviour here is unchanged from before this detection step existed. |
+| `already-scaffolded` | `project/board/`, `project/PROJECT_SUMMARY.md`, or `project/configs/workflow.json` already exists. | Tell the user this directory already has a Jenga scaffold and **stop** — do not run the scaffold script. Re-running it would silently overwrite `PROJECT_SUMMARY.md` and `workflow.json` with fresh stubs. Point them at `/continue` or `/status` instead. |
+| `existing-codebase` | The directory has real content (source, configs, docs beyond the boilerplate list) and is not already scaffolded. | **Pause. Do not scaffold.** Present the choice below and wait for an answer. |
+
+On `existing-codebase`, present this choice verbatim, per the Interaction Pattern in
+`CLAUDE.md` (numbered, free-text last):
+
+    This directory already contains code that wasn't built through Jenga. How would
+    you like to proceed?
+    1. Run /uncharted onboard first, to analyze the existing code and backfill the
+       board before scaffolding
+    2. Scaffold fresh anyway, leaving the board empty (the existing code is never
+       modified either way — onboard mode and fresh scaffolding are both board-only)
+    3. Abort — don't scaffold, don't run /uncharted
+    4. Other (describe below)
+
+- **Option 1** — invoke `/uncharted onboard`. It analyzes the existing code and backfills
+  the board; it never modifies, moves, or restructures application code. Once it
+  finishes, the directory now has `project/PROJECT_SUMMARY.md` etc., so re-running this
+  detection step returns `already-scaffolded` — there is nothing left to scaffold.
+- **Option 2** — continue to step 2 and scaffold fresh. Note in your response that the
+  board will start empty despite the directory containing pre-existing code, since the
+  user explicitly chose that.
+- **Option 3** — stop here. Do not run the scaffold script and do not invoke `/uncharted`.
+- **Option 4** — handle the free-text response on its own merits.
+
+If the run is non-interactive (no user available to answer), default to **option 3
+(abort)**. Unlike the visibility question in step 2, none of these three choices is a
+no-op: running `/uncharted onboard` unattended commits an analysis pass the user never
+asked for, and scaffolding fresh unattended silently discards pre-existing code from the
+board exactly as `/init` did before this step existed. Aborting is the only choice that
+changes nothing on disk, so it is the only safe default.
+
+Never treat `existing-codebase` as if it were `empty`, and never skip straight to step 2
+on that verdict without the user (or the non-interactive default) choosing to.
+
+### 2. Ask how JengaAgent's working files should appear
+
+Ask the user this question, verbatim, before running any script:
+
+    How should JengaAgent's own working files (project/ — the scrum board, todo.md,
+    queue/, rapports/, and logs/) appear in this project?
+    1. Visible — keep them at `project/`, tracked and visible in directory listings
+    2. Ignored — keep them at `project/` but add them to `.gitignore` so they are 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 is one of `visible` or `ignored`.
+
+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 can never silently relocate directories or edit `.gitignore`.
+
+> A third mode, `hidden` (dot-prefixing `project/` to `.project/`, matching the
+> `.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
+> follow-up to reintroduce it once fixed.
+
+Carry the chosen value into step 3. Do not apply it yourself — the script owns all
+of the mechanical work.
+
+### 3. Run the scaffold script
+
+Execute the init script from the project root, passing the choice from step 2:
+
+```bash
+chmod +x ./scripts/init.sh && ./scripts/init.sh --visibility <visible|ignored>
+```
+
+Omitting `--visibility` falls back to the `JENGA_PROJECT_FILES_VISIBILITY`
+environment variable, then to `visible`.
+
 This script handles all scaffolding in one step:
 1. Initializes the git repository
 2. Creates `.gitignore`
@@ -36,10 +115,24 @@ This script handles all scaffolding in one step:
 7. Creates `project/data/baselines.json`
 8. Creates `project/logs/events.json`
 9. Creates `docs/STRATEGY.md` — a strategic brief stub intended for investors, partners, and the product team
-10. Stages and commits all files with the message `init: scaffold project structure and workflow config`
+10. Creates `CHANGELOG.md` from the shared template — a running log of notable changes, seeded with an `[Unreleased]` section
+11. 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
+12. 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.
+
+If the script fails, check that you are in the project root and that git and `jq`
+are available.
 
-If the script fails, check that you are in the project root and that git is available.
+See `skills/distribute/CONFIG_SCHEMA.md` for the full `project_files_visibility`
+field reference.
 
-### 11. Prompt next step
+### 4. Prompt next step
 
-Inform the user that setup is complete. 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.
+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
+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/init/assets/directory_structure.txt

@@ -1,6 +1,7 @@
 project/board/epics
 project/board/stories
 project/board/tasks
+project/instructions
 project/configs
 project/data
 project/queue

package/skills/init/assets/workflow_template.json

@@ -12,7 +12,7 @@
     "scrum_triggers": "project/queue/scrum_triggers.jsonl",
     "developer_triggers": "project/queue/developer_triggers.jsonl",
     "tester_triggers": "project/queue/tester_triggers.jsonl",
-    "session_handoff": "project/queue/.session_handoff.json",
+    "session_handoff": "project/queue/handoffs/",
     "logs": "project/logs",
     "data": "project/data",
     "configs": "project/configs",

package/skills/init/scripts/apply-project-visibility.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+#
+# apply-project-visibility.sh — apply the `project_files_visibility` mode to a project.
+#
+# Usage:
+#   apply-project-visibility.sh <mode> [project_root]
+#   apply-project-visibility.sh --check-only <mode>
+#
+# Modes:
+#   visible   Working files stay where they are. No-op on disk beyond the config write.
+#   ignored   Working files are added to the project's .gitignore — present on disk,
+#             never committed.
+#
+# NOTE: A third mode, `hidden` (dot-prefixing project/ -> .project/), was
+# implemented and then withdrawn before release. Testing found it functionally
+# broken: scripts/board_resolver.sh hardcodes project/configs/workflow.json
+# and never locates the rewritten path, and hooks/on_session_end.sh
+# unconditionally recreates a shadow project/ tree on every session end,
+# splitting runtime state across two trees. See
+# project/rapports/problems/E31_S05_T01-hidden-mode-path-resolution-gaps.md
+# for the full findings. Re-introducing `hidden` requires fixing both of
+# those hardcoded paths first — tracked as a follow-up /todo item.
+#
+# 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 "[visibility] $*"; }
+warn() { echo "[visibility] WARNING: $*"; }
+err()  { echo "[visibility] ERROR: $*" >&2; }
+
+usage() {
+  echo "Usage: $(basename "$0") <visible|ignored> [project_root]" >&2
+  echo "       $(basename "$0") --check-only <visible|ignored>" >&2
+  exit 1
+}
+
+# Every JengaAgent working file named in E31_S05 — the scrum board, todo.md,
+# queue/, rapports/ and logs/ — nests under this single root, so one entry
+# covers them all. `ignored` consumes this list.
+JENGA_WORKING_PATHS=("project")
+
+VALID_MODES="visible ignored"
+
+validate_mode() {
+  local mode="$1"
+  for valid in $VALID_MODES; do
+    [ "$mode" = "$valid" ] && return 0
+  done
+  err "Invalid project_files_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_visibility_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" '.project_files_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 project_files_visibility = \"$mode\" to $config"
+}
+
+# ---------------------------------------------------------------------------
+# Apply
+# ---------------------------------------------------------------------------
+
+case "$MODE" in
+  visible)
+    info "Mode 'visible' — working files stay in place; nothing to change on disk."
+    ;;
+  ignored)
+    for path in "${JENGA_WORKING_PATHS[@]}"; do
+      gitignore_append "${path}/"
+    done
+    ;;
+esac
+
+write_visibility_config "$MODE"
+
+info "Applied project_files_visibility '$MODE' to $PROJECT_ROOT"