@jenga-ai/agent 1.0.1 → 1.1.1

package/templates/SCRUM_BOARD_SCHEMA.md

@@ -26,7 +26,7 @@ project/
     developer_triggers.jsonl     Trigger queue for developer agent
     tester_triggers.jsonl        Trigger queue for tester agent
     project_summary_updates.jsonl Proposed PROJECT_SUMMARY.md edits
-    .session_handoff.json        Transient inter-session handoff (written by agent, consumed by on_session_end.sh)
+    handoffs/                    Per-session transient handoffs (written by agent, consumed by on_session_end.sh) — see `handoffs/` below
   rapports/
     problems/       Problem rapports from developer and tester
     analysis/       Analysis rapports from tester
@@ -65,6 +65,8 @@ All status fields must use one of the following exact strings:
 | `Failed`             | Tests did not pass                                         |
 | `Rejected`           | Deliberately rejected — not a test failure                 |
 | `Blocked`            | Cannot proceed; human intervention required                |
+| `Backlog`            | Epic-level only; queued but not yet prioritized for work    |
+| `Done`               | Epic-level only; all child stories/tasks closed out          |
 
 Only the **tester agent** may write status values to story and task files. Only the **scrum master** may write status values to epic files and may update story status as part of rollup.
 
@@ -86,6 +88,8 @@ dates_previously_completed:  # comma-separated list, e.g. 2026-01-15, 2026-03-22
 reopened_on:                 # comma-separated list, e.g. 2026-02-01, 2026-04-10
 reopened_reason:             # comma-separated list, e.g. "Scope expanded", "Bug found post-release"
 docs: []                     # optional list of repo-relative documentation paths, e.g. ["README.md", "docs/API.md"]
+epic_scope_approval: false     # set to true by the human operator only when any task in this epic has execution_scope: epic
+provenance:                  # optional; only valid value is `backfilled` (epic reverse-engineered from pre-existing code by `/uncharted onboard`). Omit for normally-authored epics.
 stories:
   - E##_S##
   - E##_S##
@@ -101,6 +105,8 @@ stories:
 - <Concrete, testable criterion>
 ```
 
+> **`epic_scope_approval`** — This field is **set by the human operator only**. Neither the scrum-master nor the developer agent may set it to `true`. It must be `true` before any task with `execution_scope: epic` can be executed. Its absence is equivalent to `false`.
+
 ### Story — `E##_S##_<slug>.md`
 
 ```markdown
@@ -116,6 +122,11 @@ dates_previously_completed:  # comma-separated list, e.g. 2026-01-15, 2026-03-22
 reopened_on:                 # comma-separated list, e.g. 2026-02-01, 2026-04-10
 reopened_reason:             # comma-separated list, e.g. "Scope expanded", "Bug found post-release"
 docs: []                     # optional list of repo-relative documentation paths, e.g. ["README.md", "docs/API.md"]
+crucial_level:                # optional; advisory | gated | locked; absence means no elevated caution
+crucial_set_by:                # required when crucial_level is set; user | scrum-master | <agent>-escalation
+crucial_note:                  # required when crucial_level is set; free-text justification
+crucial_declined:              # optional; true only; absence means no declined proposal is on record
+crucial_declined_note:         # required when crucial_declined: true; free-text: heuristic matched, proposed tier, date declined
 tasks:
   - E##_S##_T##
   - E##_S##_T##
@@ -150,6 +161,17 @@ reopened_on:                 # comma-separated list, e.g. 2026-02-01, 2026-04-10
 reopened_reason:             # comma-separated list, e.g. "Scope expanded", "Bug found post-release"
 assigned_to: developer | tester | scrum-master
 docs: []                     # optional list of repo-relative documentation paths, e.g. ["README.md", "docs/API.md"]
+execution_scope: task          # task | story | epic | inline; omit for legacy tasks (defaults to task)
+needs_docs: true               # boolean; omit for legacy tasks (defaults to true)
+scope_rationale: ""            # required when execution_scope is set; must contain a numeric/file-count claim
+jenga_assigned: true           # boolean; true = machine-assigned, false = human override
+override_justification: ""     # required when jenga_assigned: false
+epic_scope_approval: false     # required (as true) when execution_scope: epic; set by human operator only
+crucial_level:                  # optional; advisory | gated | locked; absence means no elevated caution
+crucial_set_by:                  # required when crucial_level is set; user | scrum-master | <agent>-escalation
+crucial_note:                    # required when crucial_level is set; free-text justification
+crucial_declined:                # optional; true only; absence means no declined proposal is on record
+crucial_declined_note:           # required when crucial_declined: true; free-text: heuristic matched, proposed tier, date declined
 ---
 
 # Task: <Title>
@@ -164,6 +186,23 @@ docs: []                     # optional list of repo-relative documentation path
 - [ ] <Verifiable criterion>
 ```
 
+> **Backward compatibility:** Tasks that omit all six new fields (`execution_scope`, `needs_docs`, `scope_rationale`, `jenga_assigned`, `override_justification`, `epic_scope_approval`) are treated as `execution_scope: task` / `needs_docs: true` and are processed without error. Agents must not reject board files that lack these fields.
+
+### Runtime-written task fields
+
+These four fields are **not authored by hand**. They are appended to a task's frontmatter after execution and are absent from any task that has not yet run. They are listed here so that tooling — in particular `scripts/validate-board.sh` — recognises them as valid rather than unknown.
+
+| Field | Written by | Meaning |
+|---|---|---|
+| `actual_files_changed` | `/close-story` | Count of files changed by the task, extracted from its EST-tagged commits |
+| `actual_lines_delta` | `/close-story` | Net line delta for the task, from the same extraction |
+| `scope_divergence_flag` | `/close-story` | Set when actual diff stats exceed the thresholds that justified the assigned `execution_scope` |
+| `divergence_flag` | `/do` | Set to `true` by the intent-vs-diff check when a `needs_docs: false` task touched unregistered files |
+
+All four are advisory and non-blocking — they record evidence for later review and never change a task's Passed/Failed outcome.
+
+> `task_changed_files` is **not** a frontmatter field despite the similar name. It lives in the bundle manifest at `project/queue/bundle-<E##_S##>.json`, keyed by task ID.
+
 ---
 
 ## Story Format Standards
@@ -172,6 +211,14 @@ docs: []                     # optional list of repo-relative documentation path
 
 **`dates_previously_completed`, `reopened_on`, `reopened_reason`** — These fields are **only populated when a previously completed item is being reopened and modified**. Leave them blank on first-run items. Each value is a comma-separated list to support multiple reopen cycles.
 
+## Planning Fields
+
+**`priority`** (stories, optional) — Relative planning priority, e.g. `P0`, `P2`, or a range such as `P0-P1`. Advisory only; no agent behaviour keys off it.
+
+**`depends_on`** (stories and tasks, optional) — Board IDs this item depends on, e.g. `E19_S02`. Advisory only.
+
+> **Deprecated spellings.** `epic:`, `story:`, `date_added:`, `dependencies:`, and `reopens:` were used on older board files and are **not** valid. Use `epic_id`, `story_id`, `date_created`, `depends_on`, and the reopen tracking fields respectively. All existing files were normalised on 2026-08-19; `scripts/validate-board.sh` rejects the old spellings so the drift cannot reappear.
+
 ## Documentation Provenance Field
 
 **`docs`** — Optional YAML list of documentation files affected by the board item. Use repo-relative paths such as `README.md` or `docs/API.md`.
@@ -181,8 +228,118 @@ docs: []                     # optional list of repo-relative documentation path
 - Optionality: existing board files remain valid when `docs` is omitted.
 - Format: use a YAML list. Inline (`docs: ["README.md"]`) and expanded list styles are both valid.
 
+## Epic Provenance Field
+
+**`provenance`** (epics only, optional) — Records how the epic came to exist: whether it was
+planned through the normal Jenga workflow or reverse-engineered from code that already existed.
+
+- **Valid values:** `backfilled` — the only recognised value.
+- **`provenance: backfilled`** means the epic was generated by `/uncharted onboard` from a
+  pre-existing codebase, rather than authored through the normal planning flow (`/pi-plan`,
+  `/brainstorm`, `/todo`, or the Scrum Master breaking down a user request).
+- **Absence means normally-authored.** An epic with no `provenance` field was authored through
+  the standard planning flow. There is no explicit value for this — omission *is* the signal.
+- **Optional and backward compatible.** Every existing epic omits `provenance` and remains valid.
+  `scripts/validate-board.sh` accepts the key when present and never requires it.
+- **Scope:** epics only. Stories and tasks do not carry `provenance`; a backfilled epic's children
+  are identified by their parent, not by a marker of their own.
+
+### What `backfilled` implies
+
+A backfilled epic describes **code that already exists**. Its Purpose section documents a
+subsystem that was discovered, not a capability to be built. Consequently its stories and tasks
+describe **understanding and integration work** — documenting behaviour, adding missing tests,
+identifying risk areas, bringing the subsystem under board provenance — and **not original
+construction**. Agents and humans reading the board should not treat a backfilled epic's
+Definition of Done as a build plan, and should not assume that an incomplete-looking backfilled
+epic represents unbuilt functionality.
+
+## Execution Scope Fields (Task)
+
+These six fields control the execution footprint of a task within the `/jenga` and `/do` workflows. They are **optional** — omitting all six is valid and equivalent to `execution_scope: task` / `needs_docs: true`.
+
+**`execution_scope`**
+- Valid values: `task` | `story` | `epic` | `inline`
+- When required: optional; omit for legacy tasks (runtime default: `task`)
+- Description: defines how broadly this task's implementation touches the codebase.
+  - `task` — standard single-task scope (default)
+  - `story` — task may touch files across multiple tasks in the same story
+  - `epic` — task may touch files across stories; requires `epic_scope_approval: true` on the parent epic
+  - `inline` — trivial change (e.g. config tweak, comment, schema doc); no execution plan or summary document is needed
+
+**`needs_docs`**
+- Valid values: `true` | `false`
+- When required: optional; omit for legacy tasks (runtime default: `true`)
+- Description: when `false`, the developer agent skips writing an execution plan and execution summary for this task. Automatically implied as `false` when `execution_scope: inline`.
+
+**`scope_rationale`**
+- Valid values: any non-empty string; must include a measurable claim (e.g. a file count or line count)
+- When required: required when `execution_scope` is explicitly set to any value
+- Description: a brief justification explaining why the chosen scope is appropriate. Validators reject a blank value when `execution_scope` is present.
+
+**`jenga_assigned`**
+- Valid values: `true` | `false`
+- When required: optional; omit for legacy tasks (runtime default: `true`)
+- Description: indicates whether the execution scope was assigned by the `/jenga` orchestrator (`true`) or overridden by a human (`false`). When `false`, `override_justification` is required.
+
+**`override_justification`**
+- Valid values: any non-empty string
+- When required: required when `jenga_assigned: false`
+- Description: explains why the human operator overrode the machine-assigned scope. Must be non-empty when present.
+
+**`epic_scope_approval`**
+- Valid values: `true` | `false`
+- When required: required on the **epic** frontmatter (as `true`) before any task with `execution_scope: epic` may be executed; the task frontmatter carries this field for reference only
+- Description: the authoritative value is always read from the **epic** frontmatter, not the task. This field is **set by the human operator only** — neither the scrum-master nor the developer agent may set it to `true`. Its absence on the epic is equivalent to `false`.
+
 These rules apply to every story file written or amended by the **Scrum Master**. They are enforced at write time by `scripts/validate-story-format.sh`.
 
+## Crucial Flag Fields (Story, Task)
+
+These three fields let a story or task declare an elevated caution tier — a signal that the item carries more risk than usual and should be handled with extra care during execution and review. They are **optional** — omitting all three is valid and means no elevated caution applies.
+
+**`crucial_level`**
+- Valid values: `advisory` | `gated` | `locked`
+- When required: optional; absence means no elevated caution (same "absence is the signal" convention used by `provenance` and the execution-scope fields)
+- Description: declares the item's caution tier.
+  - `advisory` — proceed as normal but flag the elevated risk for reviewers
+  - `gated` — requires explicit confirmation before execution proceeds
+  - `locked` — execution is blocked until the tier is downgraded or cleared by an authorised party
+
+**`crucial_set_by`**
+- Valid values: `user` | `scrum-master` | `<agent>-escalation` (e.g. `developer-escalation`, `tester-escalation`)
+- When required: required when `crucial_level` is set
+- Description: records who or what set the caution tier — a human operator, the scrum-master during planning, or an agent escalating mid-execution.
+
+**`crucial_note`**
+- Valid values: any non-empty string
+- When required: required whenever `crucial_level` is set (same required-when-present pattern as `scope_rationale`)
+- Description: a free-text justification explaining why the item was assigned this caution tier. Validators reject a blank value when `crucial_level` is present.
+
+**Scope: stories and tasks only.** Epics do not carry these fields — an epic's risk gating is already handled by `epic_scope_approval` (see Execution Scope Fields above). A story or task's `crucial_level` is independent of any execution-scope value on the same item.
+
+**Backward compatibility.** Existing board files that omit all three fields (`crucial_level`, `crucial_set_by`, `crucial_note`) remain valid, exactly like the `docs` field and the execution-scope fields. Agents must not reject board files that lack them.
+
+## Declined Crucial Proposal Fields (Story, Task)
+
+These two fields record that a scrum-master heuristic proposed a `crucial_level` for this specific item (per the "Crucial Level Heuristic Proposal" step in `agents/scrum-master.md`) and the user explicitly declined it in-session. This is the **authoritative decline-tracking mechanism** — `agents/scrum-master.md`'s breakdown step checks it before evaluating the heuristic list again, so a declined proposal is not silently re-surfaced on a later breakdown pass over the same item. They follow the same "optional field, absence is the signal, backward compatible" convention already used by `docs`, `provenance`, and the execution-scope fields, and the same required-when-present pairing already used by `crucial_level`/`crucial_note`.
+
+**`crucial_declined`**
+- Valid values: `true` (the only recognised value)
+- When required: optional; absence means no declined proposal is on record for this item — same "absence is the signal" convention used by `provenance`. There is no `false` state to write: an item either has a recorded decline or it doesn't.
+- Description: a boolean marker, deliberately separate from free text, so the scrum-master breakdown step can check a single unambiguous field before re-proposing rather than parsing prose for intent.
+
+**`crucial_declined_note`**
+- Valid values: any non-empty string
+- When required: required when `crucial_declined: true` (same required-when-present pattern as `crucial_note`)
+- Description: free-text record of which heuristic(s) matched (from the fixed list in `agents/scrum-master.md`'s "Crucial Level Heuristic Proposal" section), the `crucial_level` tier that was proposed, and the date the user declined it — e.g. `"Declined 2026-08-27: matched 'schema/frontmatter contracts' heuristic, proposed advisory tier; user declined without further reason."` Validators reject a blank value when `crucial_declined` is present.
+
+**Scope: stories and tasks only** — same scope as the Crucial Flag Fields above.
+
+**Relationship to `crucial_level`.** `crucial_declined` and `crucial_level` are mutually exclusive in the normal flow: if the user *confirms* a proposal, the item gets `crucial_level`/`crucial_set_by: scrum-master`/`crucial_note` and no decline is recorded; if the user *declines*, the item gets `crucial_declined: true`/`crucial_declined_note` and none of the three `crucial_level` fields are set. A human operator may still set `crucial_level` directly on an item that also carries a recorded decline (e.g. deciding later, independent of the scrum-master's proposal, that the item should be flagged) — the fields are not validated as exclusive, only documented as normally following one path or the other.
+
+**Backward compatibility.** Existing board files that omit both fields remain valid — no item has ever had a decline recorded before this convention existed, so every pre-existing file is trivially compliant.
+
 ### Acceptance Criteria (`## Acceptance Criteria`)
 
 - **Required** — the section must exist in every story file.
@@ -199,7 +356,7 @@ These rules apply to every story file written or amended by the **Scrum Master**
 
 Run `scripts/validate-story-format.sh <path-to-story-file>` to verify a story file meets these requirements. The script exits 0 on success and non-zero with a descriptive error message on failure.
 
-Run `scripts/validate-board.sh <path-to-board-file>` to validate epic, story, or task frontmatter keys. The helper accepts optional `docs` annotations and remains backward compatible with existing board files that omit `docs`.
+Run `scripts/validate-board.sh <path-to-board-file>` to validate epic, story, or task frontmatter keys. The helper accepts optional `docs` and (on epics) `provenance` annotations, and remains backward compatible with existing board files that omit them.
 
 ---
 
@@ -215,12 +372,28 @@ Run `scripts/validate-board.sh <path-to-board-file>` to validate epic, story, or
 
 ## File Locking (Concurrency Control)
 
-Before writing to any board file, agents must:
+Board file writes (task/story/epic frontmatter updates) are enforced through `scripts/with-lock.sh`, not through agents manually implementing a check-wait-retry convention. The earlier prose-only protocol ("check for a `<filename>.lock` file, wait, retry, then create/delete it yourself") was purely advisory — nothing stopped two writers from both deciding the lock was free at the same instant. `scripts/with-lock.sh` closes that gap with a real mutual-exclusion primitive.
+
+**Usage:**
+
+```bash
+scripts/with-lock.sh <target-file> -- <command> [args...]
+```
+
+The script acquires an exclusive lock keyed to `<target-file>`, runs `<command> [args...]` only once the lock is held, and always releases the lock afterward — on success, on failure, and on `INT`/`TERM` signals. Agents (scrum-master, tester) MUST wrap every board file write through this script rather than reading/writing a `.lock` file by hand.
+
+**Lock primitive.** The script uses `mkdir "<target-file>.lock.d"` as the exclusivity check, not `flock`. `flock` is a Linux-only (`util-linux`) utility and is not available by default on macOS/BSD — this repo runs on Darwin, so a `flock`-only implementation would silently not work for every contributor on macOS. `mkdir` is atomic on every POSIX platform this project targets: when multiple processes race to create the same directory, exactly one succeeds and every other caller fails immediately (`EEXIST`) — there is no window where two callers can both believe they hold the lock.
+
+**Waiting and failure behavior.** If the lock is already held, the script polls (default every 0.2s, `WITH_LOCK_POLL_SECONDS`) until either the lock is released or a timeout elapses (default 30s, `WITH_LOCK_TIMEOUT_SECONDS`). If the timeout elapses first, the script exits `2` **without ever running the wrapped command** — a fail-safe abort, never a silent overwrite. A lock still held after `WITH_LOCK_STALE_SECONDS` (default 60s) is treated as abandoned (e.g. a crashed holder) and reclaimed; reclamation only clears the lock directory, it does not itself grant the lock, so simultaneous reclaim attempts by multiple waiters still cannot let more than one of them proceed — the next `mkdir` in each waiter's loop remains the sole arbiter.
+
+**Example — a status write wrapped in the lock:**
+
+```bash
+scripts/with-lock.sh project/board/tasks/E01_S02_T03_example.md -- \
+  bash -c 'update_task_status project/board/tasks/E01_S02_T03_example.md Passed'
+```
 
-1. Check for a `<filename>.lock` file adjacent to the target file.
-2. If the lock file exists and its modification time is less than 60 seconds ago — wait up to 10 seconds and retry once. If still locked, abort and write a problem rapport.
-3. If no lock exists (or it is stale, older than 60 seconds) — create the lock file, perform the write, then delete the lock file.
-4. Always delete the lock file in success and failure paths. Use a `trap` or equivalent cleanup.
+If a caller cannot acquire the lock within the timeout, treat it the same as the old protocol's "still locked after retry" case: abort the write and write a problem rapport rather than bypassing the script.
 
 ---
 
@@ -233,6 +406,17 @@ Before writing to any board file, agents must:
 | `security_concern`      | developer          | `project/rapports/problems/`                    |
 | `test_failure`          | tester             | `project/rapports/problems/`                    |
 | `analysis`              | tester             | `project/rapports/analysis/`                    |
+| `crucial_escalation`    | developer, tester  | `project/rapports/problems/`                    |
+
+### `crucial_escalation` — concrete-reason requirement
+
+A `crucial_escalation` rapport is filed mid-task when developer or tester discovers something that changes an item's risk profile and warrants raising its `crucial_level` (see E39 — Crucial Flag). It is routed through the same rapport/trigger queue as every other rapport type (`on_session_end.sh` → `scrum_triggers.jsonl`), since no synchronous interrupt exists for a backgrounded subagent.
+
+The rapport's reason **must include at least one concrete, checkable fact** — a specific file/path, an exact error message, a reproduction count, or a quantifiable impact (e.g. "affects 12 downstream tasks", "data loss observed on 2 of 2 reproduction attempts"). A subjective statement alone (e.g. "this seems risky", "this feels important") is **not** acceptable.
+
+This is the same numeric-claim bar already established for `scope_rationale` in `agents/scrum-master.md` (see its "scope_rationale — Mandatory Population Rules" section) — reused here deliberately so the concrete-reason standard is consistent across the codebase rather than a new one-off rule invented for this rapport type. Enforcing this rule (rejecting generic text) is scrum-master's responsibility when it reviews the rapport, not something checked at write time.
+
+A `crucial_escalation` rapport must also name the target item's ID (`E##`, `E##_S##`, or `E##_S##_T##`) whose `crucial_level` is being escalated. No new field is introduced for this — it uses the rapport's existing "Related Epic" / "Related Story" / "Related Task" header fields (see `templates/PROBLEM_RAPPORT_TEMPLATE.md`).
 
 ---
 
@@ -259,9 +443,21 @@ Before writing to any board file, agents must:
 |-------------------|---------------------|-------------------------------------------------|
 | `test_assignment` | on_session_end.sh (from developer handoff) | Implementation complete; run tests against worktree |
 
-### `.session_handoff.json` — transient, consumed by on_session_end.sh
+### `handoffs/` — per-session transient handoffs, consumed by on_session_end.sh
+
+**Directory:** `project/queue/handoffs/`
+
+Replaces the earlier single-slot `project/queue/.session_handoff.json` file (E37_S01_T01). The single fixed path allowed two sessions ending close together — an in-session tester invocation, or concurrent `/jenga` dispatch running multiple developer/tester pairs at once — to both write the same file before either write was consumed; the second write silently clobbered the first, and the loser's handoff (and, in the worst case, the task it represented) was lost with no error. Live incidents are recorded in `PROJECT_SUMMARY.md`'s E37 section.
+
+**Filename convention:** `project/queue/handoffs/<agent>-<session_id>-<task_id>.json`
+
+- `<agent>` — `scrum-master`, `developer`, or `tester` (matches the handoff body's own `agent` field).
+- `<session_id>` — the writing session's id, verbatim. This alone already makes the path collision-free, since each session has a unique id and writes its terminal handoff exactly once (the "last action of its session").
+- `<task_id>` — the primary task ID (`E##_S##_T##`) this handoff concerns, included for human-readability/debugging. For the scrum-master's batched `task_ids` array, use the first entry, or the literal string `batch` if the array is empty.
+
+Each file is written by an agent as the **last action** of its session, and is single-use: consumed and deleted by `on_session_end.sh` (per-file, immediately after routing — see `hooks/on_session_end.sh` section 4) once that session's `SessionEnd` hook fires. A file must not persist once it has been consumed. `project/queue/handoffs/*.json` is git-ignored (E37_S01_T02) precisely to enforce this structurally — the directory itself is kept via `.gitkeep`, but individual handoff files must never become durable git artifacts, since a committed one can no longer be told apart from a live pending signal by inspection alone.
 
-Written by an agent as the **last action** of its session. Consumed and deleted by `on_session_end.sh`. The file must not persist across sessions.
+**Staleness guard (E37_S01_T02):** before routing a `developer` or `tester` handoff, `on_session_end.sh` checks whether the file's `task_id` is already in a terminal board status (`Passed`, `Passed with remarks`, `Rejected`, `Done`, or `Blocked`). If so, the file is deleted without routing — it is treated as a stale leftover (e.g. one that predates this consumer logic, or one that slipped past the git-ignore rule above) rather than a live signal for already-completed work. This closed a real regression found during testing: `project/queue/handoffs/` had accumulated ~25 committed files for already-`Passed` work before this consumer logic existed to clean them up, and a bare generic glob would have resurrected all of them as fresh `test_assignment`/`story_rollup` triggers on the first `SessionEnd` run after this feature landed. The check is not applied to `scrum-master`'s batched `task_ids` handoffs (a `planning_complete` handoff's tasks are freshly created and cannot already be terminal in practice).
 
 | Field         | Required by          | Notes                                    |
 |---------------|----------------------|------------------------------------------|
@@ -288,7 +484,7 @@ Located at `project/configs/workflow.json`. Scaffolded by `/init` and owned by t
 
 ```json
 {
-  "statuses": ["Pending", "In Progress", "Passed", "Passed with remarks", "Failed", "Rejected", "Blocked"],
+  "statuses": ["Pending", "In Progress", "Passed", "Passed with remarks", "Failed", "Rejected", "Blocked", "Backlog", "Done"],
   "rapport_types": ["conflict", "implementation_blocker", "security_concern", "test_failure", "analysis"],
   "paths": {
     "board": "project/board",

package/templates/permission-levels/README.md

@@ -0,0 +1,73 @@
+# Permission Level Templates
+
+> **Distribution note:** This directory is mirrored automatically — no additional wiring is needed. `/self-sync` (`skills/self-sync/scripts/run.js`, `COPY_SET`) and `/distribute` (`distribute.config.json`, `distribute.include`) both already list `templates` as a top-level entry, and both copy that directory recursively, so `templates/permission-levels/` (including this README and all five level JSON files) rides along automatically with every sync/distribute run.
+
+This directory holds the five canonical `settings.json` permission templates that back the `/jenga-permission-level` session-switchable permission system: **Locked (1)**, **Guarded (2)**, **Standard (3)**, **Elevated (4)**, and **Unrestricted (5)**.
+
+Each level is a full `settings.json` file — `level-1-locked.json` through `level-5-unrestricted.json`. Two fields vary between them: `permissions.deny` and `autoMode.allow`. This table exists so a maintainer can see, at a glance, what each level allows and denies without diffing all 5 JSON files by hand.
+
+## Level Matrix
+
+| Level | Name | `permissions.deny` | Rationale |
+|---|---|---|---|
+| 1 | Locked | `rm *`<br>`rmdir *`<br>`dd *`<br>`mkfs *`<br>`shred *`<br>`truncate *`<br>`git push *`<br>`git reset --hard *`<br>`git clean *`<br>`chmod *`<br>`chown *`<br>`sudo *`<br>`su *`<br>`git commit *`<br>`git add *`<br>`git stash *`<br>`npm install *`<br>`npm publish *`<br>`git branch -D *`<br>`git tag *` | Maximum safety. Blocks all destructive file/git ops plus every git *write* op (commit, add, stash, branch delete, tag) and package publish/install — suitable for read-only exploration or highly sensitive sessions. |
+| 2 | Guarded (**permanent default**) | `rm *`<br>`rmdir *`<br>`dd *`<br>`mkfs *`<br>`shred *`<br>`truncate *`<br>`git push *`<br>`git reset --hard *`<br>`git clean *`<br>`chmod *`<br>`chown *`<br>`sudo *`<br>`su *` | Safe default for normal agentic work. Blocks destructive file ops, destructive/history-rewriting git ops, and permission/ownership changes, but allows normal git commit/add/stash and package installs. |
+| 3 | Standard | `dd *`<br>`mkfs *`<br>`shred *`<br>`truncate *`<br>`git push *`<br>`git reset --hard *`<br>`git clean *`<br>`chmod *`<br>`chown *`<br>`sudo *`<br>`su *` | Adds `rm *` / `rmdir *` back (Guarded minus those two) for normal file cleanup during active development, while still blocking pushes and history-rewriting git ops. |
+| 4 | Elevated | `dd *`<br>`mkfs *`<br>`shred *`<br>`truncate *`<br>`chmod *`<br>`chown *`<br>`sudo *`<br>`su *` | Adds `git push *` / `git reset --hard *` / `git clean *` back (Standard minus those three) for active development workflows that need to push and reset branches. |
+| 5 | Unrestricted | `dd *`<br>`mkfs *`<br>`shred *`<br>`truncate *`<br>`sudo *`<br>`su *` | Adds `chmod *` / `chown *` back (Elevated minus those two). Only the non-negotiable always-blocked set (see below) remains denied. |
+
+## `autoMode.allow` by Level
+
+`autoMode.allow` lists commands that are auto-approved **without a prompt** when the session is running in auto mode. It is a *friction* dial, not a *capability* dial — `permissions.deny` always wins over it — with one important exception described below.
+
+| Level | `autoMode.allow` |
+|---|---|
+| 1 · Locked | `$defaults` |
+| 2 · Guarded | `$defaults` |
+| 3 · Standard | `$defaults` |
+| 4 · Elevated | `$defaults`<br>`Bash(bash skills/mirror-public/scripts/mirror.sh*)` |
+| 5 · Unrestricted | `$defaults`<br>`Bash(bash skills/mirror-public/scripts/mirror.sh*)` |
+
+### Why mirror.sh is gated to level 4+
+
+`permissions.deny` matches the command string the agent invokes — it does **not** see what that command spawns in a subprocess. `skills/mirror-public/scripts/mirror.sh` internally runs `git reset --hard origin/<branch>` and `git push origin <branch>` against the public repo. Auto-approving the script by name therefore grants an unprompted push of repository content to a **public** repo that the deny list cannot intercept. (The push itself is a plain fast-forward `git push` — the script's `--force` flag only overrides a pre-flight safety abort, it does not force-push. The risk here is disclosure, not history loss.)
+
+Levels 1–3 deny `git push *` and `git reset --hard *`. Auto-approving `mirror.sh` at those levels would silently defeat that intent. Level 4 (Elevated) is the first tier where `git push *` and `git reset --hard *` are permitted directly, so it is the first tier where auto-approving a script that performs them is consistent.
+
+**Rule for adding future entries:** before adding a command to `autoMode.allow` at level *n*, check what it executes internally. If it performs an operation that `permissions.deny` blocks at level *n*, it belongs at a higher level instead.
+
+### Every template must carry an `autoMode` key
+
+Even the levels that only grant `$defaults` declare the block explicitly. A level switch is a **whole-file overwrite** of `.claude/settings.json` and `.agents/settings.json` — any top-level key present in the destination but absent from the template is silently dropped. A template that omitted `autoMode` would wipe the destination's block on every switch.
+
+## Always Blocked
+
+The following commands are **never removed from `permissions.deny` at any level, including level 5 (Unrestricted)**:
+
+- `dd *`
+- `mkfs *`
+- `shred *`
+- `truncate *`
+- `sudo *`
+- `su *`
+
+These are disk-destructive or privilege-escalation commands with no legitimate use case in an agentic coding session. No permission level — not even Unrestricted — removes them.
+
+## Fields That Never Vary
+
+Across all 5 templates:
+
+- `defaultMode` stays `"acceptEdits"` at every level.
+- `permissions.allow` stays `["Bash(*)"]` at every level.
+- `env` and `hooks` (`WorktreeCreate`, `WorktreeRemove`, `SessionEnd`) are identical across all 5 files.
+
+**Only `permissions.deny` and `autoMode.allow` vary between levels.** Every template is otherwise byte-identical to root `settings.json`, and root `settings.json` matches `level-2-guarded.json` exactly — Guarded being the permanent default.
+
+> **Superseded (2026-08-23):** epic E33 originally settled on "`autoMode` is never used at any level" and "only `permissions.deny` varies". That decision was revisited after it emerged that auto-approving `mirror.sh` by script name bypasses the `git push *` deny at levels 1–3 (see the section above). `autoMode.allow` is now a second, deliberately tiered axis.
+
+## Guarded (Level 2) Is the Permanent Default
+
+There is no separate "default level" config number. Level 2 (Guarded) is conceptually always the project's permanent default.
+
+- To change the **permanent, project-wide default**, a maintainer edits `templates/permission-levels/level-2-guarded.json` directly.
+- Running `/jenga-permission-level <n>` only changes the **current session's** active level (by copying the matching template into `.claude/settings.json` and `.agents/settings.json` and recording the level in `.jenga-permission-level.json`) — it does not modify the permanent default, and the scrum-master resets a session back to Guarded at the start of every session it starts.

package/templates/permission-levels/level-1-locked.json

@@ -0,0 +1,71 @@
+{
+  "defaultMode": "acceptEdits",
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  },
+  "autoMode": {
+    "allow": [
+      "$defaults"
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "Bash(*)"
+    ],
+    "deny": [
+      "Bash(rm *)",
+      "Bash(rmdir *)",
+      "Bash(dd *)",
+      "Bash(mkfs *)",
+      "Bash(shred *)",
+      "Bash(truncate *)",
+      "Bash(git push *)",
+      "Bash(git reset --hard *)",
+      "Bash(git clean *)",
+      "Bash(chmod *)",
+      "Bash(chown *)",
+      "Bash(sudo *)",
+      "Bash(su *)",
+      "Bash(git commit *)",
+      "Bash(git add *)",
+      "Bash(git stash *)",
+      "Bash(npm install *)",
+      "Bash(npm publish *)",
+      "Bash(git branch -D *)",
+      "Bash(git tag *)"
+    ]
+  },
+  "hooks": {
+    "WorktreeCreate": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "NAME=$(jq -r '.name')\n. \"$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh\"\nDIR=\"$JENGA_PROJECT_DIR/.claude/worktrees/$NAME\"\ngit worktree add \"$DIR\" -b \"$NAME\" 2>&1\necho \"$DIR\"\n"
+          }
+        ]
+      }
+    ],
+    "WorktreeRemove": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel)/scripts/worktree-remove-guard.sh\"\n"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "async": true,
+            "command": ". \"$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh\" && \"$JENGA_PROJECT_DIR\"/.claude/hooks/on_session_end.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/permission-levels/level-2-guarded.json

@@ -0,0 +1,64 @@
+{
+  "defaultMode": "acceptEdits",
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  },
+  "autoMode": {
+    "allow": [
+      "$defaults"
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "Bash(*)"
+    ],
+    "deny": [
+      "Bash(rm *)",
+      "Bash(rmdir *)",
+      "Bash(dd *)",
+      "Bash(mkfs *)",
+      "Bash(shred *)",
+      "Bash(truncate *)",
+      "Bash(git push *)",
+      "Bash(git reset --hard *)",
+      "Bash(git clean *)",
+      "Bash(chmod *)",
+      "Bash(chown *)",
+      "Bash(sudo *)",
+      "Bash(su *)"
+    ]
+  },
+  "hooks": {
+    "WorktreeCreate": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "NAME=$(jq -r '.name')\n. \"$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh\"\nDIR=\"$JENGA_PROJECT_DIR/.claude/worktrees/$NAME\"\ngit worktree add \"$DIR\" -b \"$NAME\" 2>&1\necho \"$DIR\"\n"
+          }
+        ]
+      }
+    ],
+    "WorktreeRemove": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel)/scripts/worktree-remove-guard.sh\"\n"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "async": true,
+            "command": ". \"$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh\" && \"$JENGA_PROJECT_DIR\"/.claude/hooks/on_session_end.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/permission-levels/level-3-standard.json

@@ -0,0 +1,62 @@
+{
+  "defaultMode": "acceptEdits",
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  },
+  "autoMode": {
+    "allow": [
+      "$defaults"
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "Bash(*)"
+    ],
+    "deny": [
+      "Bash(dd *)",
+      "Bash(mkfs *)",
+      "Bash(shred *)",
+      "Bash(truncate *)",
+      "Bash(git push *)",
+      "Bash(git reset --hard *)",
+      "Bash(git clean *)",
+      "Bash(chmod *)",
+      "Bash(chown *)",
+      "Bash(sudo *)",
+      "Bash(su *)"
+    ]
+  },
+  "hooks": {
+    "WorktreeCreate": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "NAME=$(jq -r '.name')\n. \"$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh\"\nDIR=\"$JENGA_PROJECT_DIR/.claude/worktrees/$NAME\"\ngit worktree add \"$DIR\" -b \"$NAME\" 2>&1\necho \"$DIR\"\n"
+          }
+        ]
+      }
+    ],
+    "WorktreeRemove": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$(git rev-parse --show-toplevel)/scripts/worktree-remove-guard.sh\"\n"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "async": true,
+            "command": ". \"$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh\" && \"$JENGA_PROJECT_DIR\"/.claude/hooks/on_session_end.sh"
+          }
+        ]
+      }
+    ]
+  }
+}