@jenga-ai/agent 3.4.0 → 3.6.0

package/README.md

@@ -31,6 +31,34 @@ Jenga AI solves each of these with structure: persistent engineering context mai
 
 ---
 
+## How Jenga AI's Agentic Workflow Works
+
+```
+j.init → j.pi-plan → j.todo → j.do
+                              │
+                     Developer agent
+                     (isolated worktree, commits)
+                           │
+                     Tester agent
+                     (validates, updates board status)
+                           │
+                     SessionEnd hook
+                     (writes triggers to queue)
+                           │
+                     Scrum Master (next session)
+                     (processes queue, rollups, unblocks)
+```
+
+| Mechanism | Location | Purpose |
+|---|---|---|
+| Scrum board | `project/board/` | Epics, stories, tasks with structured frontmatter |
+| Trigger queue | `project/queue/scrum_triggers.jsonl` | Async handoff to Scrum Master |
+| Event log | `project/logs/events.json` | Append-only audit trail |
+| Rapport system | `project/rapports/` | Problem/analysis reports by Developer and Tester |
+| File locking | `<file>.lock` adjacent to board files | Concurrency control for parallel agents |
+
+---
+
 ## What You Get
 
 - **Three specialised agents** — Scrum Master, Developer, Tester — each with a distinct role and no self-graded work
@@ -60,83 +88,6 @@ The Tester doesn't read your code and form an opinion about it. It executes the
 
 ---
 
-## Examples
-
-### A Real Session, On This Repo
-
-Not a demo — this is what actually produced the section you're reading.
-
-The conversation starts with a request to align this README's language and content with a positioning plan drafted for this epic (E41):
-
-```
-j.improve E41: I want to make some adjustments to the README in both
-language as well as content to better match [the E41 positioning plan]
-[...]
-```
-
-That plan already existed, so the copy gets edited directly — no need to re-run a fresh analysis pass just to re-derive it. A few edits later, ten more issues surface, one with an `j.brainstorm` request attached:
-
-```
-Then do a j.todo on this, as there are more places that should be
-edited based on that scrutiny rapport:
-* Remove warning banner about Copilot conflict
-[...]
-* Fewer, better and more relatable examples, we should
-  j.brainstorm this so I can send examples from real world usecases
-[...]
-* Should we really display the entire Skill list here?
-[...]
-```
-
-`j.todo` classifies the ten items into two stories: nine mechanical README fixes (`E41_S10`), and the Examples section you're reading right now (`E41_S11`) — carved out and held back specifically because of that `j.brainstorm` request, since a real example had to come from the user, not be invented.
-
-Once `E41_S10` is on the board, it's picked to run first. The Scrum Master reads the story and decomposes it into seven tasks, executed through `j.do`. Five are small, single-file text fixes deemed `--trivial` — they run inline, smoke-tested and committed directly, no worktree needed. Two need an editorial call — one of them being which skills are "foundational" enough to stay inline — those escalate to a real git worktree with a Developer and a Tester. The Tester independently re-verifies the diff, catches one file the Developer missed, fixes it, and queues the story for rollup. The Scrum Master processes that queue next: `E41_S10` → `Passed`. Epic `E41` stays `In Progress` — three other stories are still open.
-
-Then, circling back to the deferred request:
-
-```
-Jenga AI: [...] Remaining open thread from this session: E41_S11
-(Examples rework) is on the board but not started — it's gated on
-a j.brainstorm session where you supply real-world use cases. Want
-to do that now, or leave it queued?
-
-You: do it now
-```
-
-`j.brainstorm` opens for the gated story — the session you're reading right now, working out what this example should even say.
-
-Nobody hand-wrote this task breakdown. The board did it, the routing rules decided what needed a real worktree versus what could run inline, and the Tester — not the agent that made the edits — decided when each piece was actually done. The board entries are real: `E41_S10` and `E41_S11`.
-
----
-
-## How Jenga AI's Agentic Workflow Works
-
-```
-j.init → j.pi-plan → j.todo → j.do
-                              │
-                     Developer agent
-                     (isolated worktree, commits)
-                           │
-                     Tester agent
-                     (validates, updates board status)
-                           │
-                     SessionEnd hook
-                     (writes triggers to queue)
-                           │
-                     Scrum Master (next session)
-                     (processes queue, rollups, unblocks)
-```
-
-| Mechanism | Location | Purpose |
-|---|---|---|
-| Scrum board | `project/board/` | Epics, stories, tasks with structured frontmatter |
-| Trigger queue | `project/queue/scrum_triggers.jsonl` | Async handoff to Scrum Master |
-| Event log | `project/logs/events.json` | Append-only audit trail |
-| Rapport system | `project/rapports/` | Problem/analysis reports by Developer and Tester |
-| File locking | `<file>.lock` adjacent to board files | Concurrency control for parallel agents |
-
----
-
 ## Agents
 
 | Agent | Role | Owns |
@@ -161,6 +112,13 @@ Each agent is defined in `.agents/agents/`. They communicate exclusively through
 npm install -g @jenga-ai/agent
 ```
 
+> **pnpm or `--ignore-scripts`?** Jenga's install relies on a `postinstall` lifecycle script to
+> mirror `skills/`/`agents/` into your project — if your package manager blocks lifecycle
+> scripts by default (pnpm v8+) or you install with `--ignore-scripts`/`ignore-scripts=true`,
+> the install will silently produce none of the framework files with no error shown. See
+> [`docs/distribution.md`](docs/distribution.md#prerequisite--lifecycle-scripts-must-be-allowed-to-run-e26_s09)
+> for the exact npm/pnpm opt-in step.
+
 Or clone directly:
 
 1. **Clone or copy this repo** into your project's root.
@@ -251,7 +209,7 @@ j.brainstorm → j.todo → j.do → j.commit
 
 Calling `j.playbook` with no id prints a table of every available playbook (id, name, and steps) instead of resolving one.
 
-Nothing executes until you confirm the chain, and any step can be unchecked first. `brainstorm-to-mirror` extends the same chain through `j.dev-done` and `j.mirror-public` for a full public release; `understand-then-ship` prepends `j.uncharted` investigation for unfamiliar code before running the same pipeline.
+Nothing executes until you confirm the chain, and any step can be unchecked first. `understand-then-commit` prepends `j.uncharted` investigation for unfamiliar code before running that same pipeline — useful when the change touches code you don't fully understand yet. No built-in playbook publishes or mirrors on your behalf: build chains terminate at `j.commit`, and publishing stays an explicit, separately invoked act.
 
 When a step forwards its result into the next one, that value has a declared **output type** (a plain string, a list of board IDs, a list of files) so the chain can be validated before it runs. See [Getting Started](https://samwelmunga.github.io/jenga-npm/getting-started.html#how-playbooks-know-what-a-skill-produces) for how that works.
 
@@ -259,6 +217,55 @@ Want your own recurring chain? `j.playbook-new` walks you through authoring one
 
 ---
 
+## Example
+
+### A Real Session, On This Repo
+
+Not a demo — this is what actually produced the section you're reading.
+
+The conversation starts with a request to align this README's language and content with a positioning plan drafted for this epic (E41):
+
+```
+j.improve E41: I want to make some adjustments to the README in both
+language as well as content to better match [the E41 positioning plan]
+[...]
+```
+
+That plan already existed, so the copy gets edited directly — no need to re-run a fresh analysis pass just to re-derive it. A few edits later, ten more issues surface, one with an `j.brainstorm` request attached:
+
+```
+Then do a j.todo on this, as there are more places that should be
+edited based on that scrutiny rapport:
+* Remove warning banner about Copilot conflict
+[...]
+* Fewer, better and more relatable examples, we should
+  j.brainstorm this so I can send examples from real world usecases
+[...]
+* Should we really display the entire Skill list here?
+[...]
+```
+
+`j.todo` classifies the ten items into two stories: nine mechanical README fixes (`E41_S10`), and the Examples section you're reading right now (`E41_S11`) — carved out and held back specifically because of that `j.brainstorm` request, since a real example had to come from the user, not be invented.
+
+Once `E41_S10` is on the board, it's picked to run first. The Scrum Master reads the story and decomposes it into seven tasks, executed through `j.do`. Five are small, single-file text fixes deemed `--trivial` — they run inline, smoke-tested and committed directly, no worktree needed. Two need an editorial call — one of them being which skills are "foundational" enough to stay inline — those escalate to a real git worktree with a Developer and a Tester. The Tester independently re-verifies the diff, catches one file the Developer missed, fixes it, and queues the story for rollup. The Scrum Master processes that queue next: `E41_S10` → `Passed`. Epic `E41` stays `In Progress` — three other stories are still open.
+
+Then, circling back to the deferred request:
+
+```
+Jenga AI: [...] Remaining open thread from this session: E41_S11
+(Examples rework) is on the board but not started — it's gated on
+a j.brainstorm session where you supply real-world use cases. Want
+to do that now, or leave it queued?
+
+You: do it now
+```
+
+`j.brainstorm` opens for the gated story — the session you're reading right now, working out what this example should even say.
+
+Nobody hand-wrote this task breakdown. The board did it, the routing rules decided what needed a real worktree versus what could run inline, and the Tester — not the agent that made the edits — decided when each piece was actually done. The board entries are real: `E41_S10` and `E41_S11`.
+
+---
+
 ## When to Use Jenga AI
 
 **Use it when:**

package/agents/developer.md

@@ -215,7 +215,7 @@ This list is fixed and verbatim across both this file and `agents/tester.md` —
 
 **Effect — forced inline scope.** `execution_scope` is force-set to `inline` for any `locked` task, overriding whatever scope `j.jenga`'s Execution Scope Assignment heuristics would otherwise assign — or auto-correcting a wrong value in place, with a logged `override_justification` note explaining the correction. The concrete mechanism is `skills/jenga/SKILL.md` Phase 0.5's **Rule 4 — `crucial_level: locked` forces `execution_scope: inline`** (added by E39_S03_T03).
 
-**Effect — dispatch-time rejection of backgrounding.** A `locked` task can never be routed to a background subagent, a worktree-isolated session, or a bundled `j.jenga` story-batch execution, regardless of what its `execution_scope` value currently reads. This is enforced at two separate points, both added by E39_S03_T04: `skills/jenga/SKILL.md` Phase 3.5 step 5's **Guard: locked-task disqualifier (defense-in-depth)**, which disqualifies any story containing a `locked` task from the bundle path before dispatch, and `skills/do/SKILL.md` Section 4.2's **Locked-task dispatch guard (defense-in-depth)**, which forces the inline execution path (no worktree, no developer subagent) at the point of dispatch even if `execution_scope` somehow still reads something other than `inline`.
+**Effect — dispatch-time rejection of backgrounding.** A `locked` task can never be routed to a background subagent, a worktree-isolated session, or a bundled `j.jenga` story-batch execution, regardless of what its `execution_scope` value currently reads. This is enforced at two separate points, both added by E39_S03_T04: `skills/jenga/SKILL.md` Phase 3.5 step 5's **Guard: locked-task disqualifier (defense-in-depth)**, which disqualifies any story containing a `locked` task from the bundle path before dispatch, and `skills/j-do/SKILL.md` Section 4.2's **Locked-task dispatch guard (defense-in-depth)**, which forces the inline execution path (no worktree, no developer subagent) at the point of dispatch even if `execution_scope` somehow still reads something other than `inline`.
 
 **No agent-discretion obligation.** Unlike `advisory` (a reporting-cadence habit you must remember to keep up) and `gated` (a confirmation you must actively pause and perform), `locked` requires no judgment call from you at all. It is fully enforced by pre-flight validation (Rule 4) and dispatch-time guards (the Phase 3.5 and `j.do` guards above) before you ever begin work on the task — there is no step in this tier that depends on you noticing or remembering anything. Your only obligation is to recognize that a `locked` task will always run in the current foreground session, and to never manually route around that guarantee — for example, do not spin up your own background subagent or a separate worktree-isolated session to "help" with a `locked` task, even if it seems more efficient. If a locked task ever reaches you already running in a background or worktree-isolated context, treat that as a guard failure worth flagging (see Rapport System), not something to quietly work through.
 

package/agents/scrum-master.md

@@ -74,10 +74,28 @@ This is a self-contained procedure, not a session-start-only step. It may be inv
        4. **Reject branch** — if the reason is generic or non-concrete, do not write any of `crucial_level` / `crucial_set_by` / `crucial_note` to the target item. Instead, decline the escalation using the same `.IGNORE.md` convention already documented in `agents/tester.md`'s "IGNORE.md — skipping resolved rapports" section: rename the rapport file to `<name>.IGNORE.md` and append an Ignore Log entry stating the escalation was declined for lacking a concrete reason. This keeps the declined rapport from being silently re-surfaced as a fresh `rapport_review` trigger on a future `on_session_end.sh` scan, since that scan's new-rapport detection skips `*.IGNORE.md` files.
        5. **Report back** — in both branches, name the target item and the decision made (accepted at tier X with `crucial_set_by`/`crucial_note` set, or declined for lacking a concrete reason) as part of the existing "Report to the user" step below (Session Start — Queue Processing, item 3); no separate reporting step is needed.
        6. **This is the only path** by which a mid-task agent request results in a `crucial_level` board write. Developer and tester never write `crucial_level`, `crucial_set_by`, or `crucial_note` directly to a board file themselves under any circumstance — they may only *request* the change via a `crucial_escalation` rapport, and the actual frontmatter write happens here, exclusively by scrum-master, closing the loop described in E39's Purpose section ("the actual frontmatter write still goes through scrum-master, never the subagent itself").
+     - **Rapport-sourced idea/topic detection (E35_S03_T02) — runs for every rapport processed under `rapport_review`, regardless of `Type`, in addition to (never instead of) the backlog-or-`Failed` handling above and the `crucial_escalation` special case above.** For each rapport, apply one further LLM judgment: does this rapport surface a distinct idea or topic not already captured in an existing epic/story/task or `project/ideas.md` entry? This mirrors the "Crucial Level Heuristic Proposal" propose-then-confirm shape (evaluation → proposal → same-session confirmation → write, or decline → record and suppress re-proposal) documented later in this file — read that section for the pattern this step reuses.
+       1. **Skip check — already-handled rapports.** Before evaluating a rapport for this step, check both of the following. If either is true, skip idea-detection for this rapport entirely and move on to the next rapport (this does not affect the rapport's normal backlog-or-`Failed` or `crucial_escalation` handling, which always runs regardless):
+          - `project/ideas.md` already contains a line tagged `<!-- rapport: <this rapport's file path> -->` — a rapport-sourced idea from this rapport was already confirmed and captured in a prior session, per the source-rapport link convention `skills/j-idea/SKILL.md` documents (E35_S03_T01).
+          - The rapport file itself already contains an `## Idea Detection Log` section (written by the decline branch below) — a proposal for this rapport was already made and declined in a prior session.
+       2. **Evaluate** — read the rapport's Summary, Context, and Problem Description sections and judge whether they surface a distinct idea or topic genuinely not already tracked anywhere on the board (`project/board/epics/`, `project/board/stories/`, `project/board/tasks/`) or in `project/ideas.md`. If nothing distinct surfaces, do nothing further for this rapport under this step.
+       3. **Propose** — if a distinct idea is found, state the proposed idea text to the user in-session and ask for confirmation. Do not add anything to `project/ideas.md` without it. Apply the same same-session-only discipline as the Confirm-Before-Write Gate below: if the session ends before the user confirms, the proposal is dropped — not persisted, not carried forward — and the rapport is simply re-evaluated fresh (subject to the skip check above) on a future `rapport_review` pass.
+       4. **On confirm** — append the idea to `project/ideas.md` using the exact same mechanism `j.idea` uses: `bash "$([ -f scripts/idea_manager.sh ] && echo scripts/idea_manager.sh || echo node_modules/@jenga-ai/agent/scripts/idea_manager.sh)" add '<idea text> <!-- rapport: <path to this rapport> -->'` — untagged (no `PROMOTED`/`REJECTED` at capture time), with the source-rapport link recorded via the `<!-- rapport: <path> -->` inline-comment convention already defined in `skills/j-idea/SKILL.md`'s "Source-Rapport Link Convention" subsection. Scrum-master does **not** author a board file directly from this step — the idea stays in `project/ideas.md` until separately promoted, exactly like any other `j.idea` entry (promotion is re-running `j.brainstorm` on it, per `skills/j-idea/SKILL.md`).
+       5. **On decline** — do not add anything to `project/ideas.md`. Instead, append the following section to the rapport file itself (a new, distinctly-named section — do **not** reuse the rapport template's existing `## Ignore Log` section, which is reserved for fully resolving/superseding the whole rapport via the `.IGNORE.md` rename convention; a declined idea proposal does not mean the rapport's underlying problem is resolved, so its normal backlog-or-`Failed`/`crucial_escalation` handling must be unaffected):
+          ```
+          ## Idea Detection Log
+          _Populated by scrum-master when a rapport-derived idea proposal is declined by the user._
+
+          **Declined by:** User
+          **Date:** YYYY-MM-DD (UTC)
+          **Proposed idea:** <one-line idea text that was proposed>
+          ```
+          This is the same non-re-proposal guarantee as `crucial_declined` (see "Decline Handling" under "Crucial Level Heuristic Proposal" below), adapted for a rapport file, which carries no frontmatter of its own to hold a boolean flag: the presence of this section is exactly what the skip check in step 1 above looks for, so a declined proposal is never re-surfaced on a future `rapport_review` pass over the same rapport. A decline here is scoped to this one rapport only — it never suppresses idea-detection evaluation on any other rapport, including similar ones.
+       6. **Report back** — name any rapports where an idea was proposed and the outcome (captured to `project/ideas.md`, or declined) as part of the existing "Report to the user" step below (Session Start — Queue Processing, item 3); no separate reporting step is needed.
    - `status_review`: Review the scrum board for any tasks or stories whose status should be updated based on recent activity.
    - `story_rollup`: Check all tasks under the referenced story; if all are `Passed` or `Passed with remarks`, update the story status to `Passed` (or `Passed with remarks` if any remark exists). Then check epic rollup (see Rollup Logic).
-   - `elicitation_resume`: A `j.uncharted` conversational architecture elicitation session (`onboard`'s default flow, or `segment --mode investigate` — E20_S08_T03) ended mid-run without converging. Read `state_file` (`project/queue/elicitation-state/<elicitation_id>.json`, written by `skills/uncharted/scripts/elicitation-state.sh`) to see exactly where it left off — which nodes already converged, which are still pending or flagged, and any directory-triage/checkpoint data already confirmed — then resume the conversational flow documented in `skills/uncharted/SKILL.md`'s Multi-Session Persistence subsection from that point rather than restarting the elicitation from scratch. If the state file is missing or unreadable, report that to the user rather than silently starting a fresh elicitation under the same id.
-   - `capacity_starvation`: `skills/do/SKILL.md`'s per-session concurrency cap (E32_S15) blocked the same board item for 3 consecutive dispatch waves because its role (`developer` or `tester`) stayed at cap. Surface a plain warning naming the affected item and its consecutive-block wave count, suggesting the configured cap (`max_concurrent_developers` / `max_concurrent_testers` in `project/configs/scope-thresholds.json`) may be too low or the session may be starved. No automatic remediation — this trigger is informational only.
+   - `elicitation_resume`: A `j.uncharted` conversational architecture elicitation session (`onboard`'s default flow, or `segment --mode investigate` — E20_S08_T03) ended mid-run without converging. Read `state_file` (`project/queue/elicitation-state/<elicitation_id>.json`, written by `skills/j-uncharted/scripts/elicitation-state.sh`) to see exactly where it left off — which nodes already converged, which are still pending or flagged, and any directory-triage/checkpoint data already confirmed — then resume the conversational flow documented in `skills/j-uncharted/SKILL.md`'s Multi-Session Persistence subsection from that point rather than restarting the elicitation from scratch. If the state file is missing or unreadable, report that to the user rather than silently starting a fresh elicitation under the same id.
+   - `capacity_starvation`: `skills/j-do/SKILL.md`'s per-session concurrency cap (E32_S15) blocked the same board item for 3 consecutive dispatch waves because its role (`developer` or `tester`) stayed at cap. Surface a plain warning naming the affected item and its consecutive-block wave count, suggesting the configured cap (`max_concurrent_developers` / `max_concurrent_testers` in `project/configs/scope-thresholds.json`) may be too low or the session may be starved. No automatic remediation — this trigger is informational only.
    - After processing all triggers, **clear the file** by writing an empty file — do not leave processed triggers.
 
 2. **Check `project/queue/project_summary_updates.jsonl`** — If non-empty, review each proposed update and apply, revise, or reject it with a short note. Clear the file after processing.

package/agents/tester.md

@@ -167,7 +167,7 @@ Always include the sender object in the response.
 
 **Trigger.** During steps 4-6 of "Invoked for test implementation and/or execution" above, you find a defect. Before defaulting to step 9's rapport path, classify it: is this **mechanical** (safe to fix in place) or does it **need a rapport** (a design decision or real risk is involved)? This classification is what determines which of the two remediation paths below you take — it is not optional bookkeeping, and it happens at the moment the defect is found, not retroactively.
 
-**Motivating case.** `project/rapports/analysis/E42_S04-execution-overhead-postmortem.md` Finding 3: the tester found `skills/dev-done/scripts/classify-commit-outcome.sh` committed without its executable bit (`chmod +x`) plus a dead, unreachable error branch. Both were one-line-class fixes, but the only path available at the time was the full formal one — a `test_failure` rapport, a separate developer fix commit, a re-verification pass, and a second complete `j.self-sync` mirror run. That produced 3 of the task's 6 total commits for defects that needed no design judgment at all. This subsection exists so that pattern doesn't repeat.
+**Motivating case.** `project/rapports/analysis/E42_S04-execution-overhead-postmortem.md` Finding 3: the tester found `skills/j-dev-done/scripts/classify-commit-outcome.sh` committed without its executable bit (`chmod +x`) plus a dead, unreachable error branch. Both were one-line-class fixes, but the only path available at the time was the full formal one — a `test_failure` rapport, a separate developer fix commit, a re-verification pass, and a second complete `j.self-sync` mirror run. That produced 3 of the task's 6 total commits for defects that needed no design judgment at all. This subsection exists so that pattern doesn't repeat.
 
 **Qualifying examples (mechanical — fix in place).**
 - A missing executable bit or other permission-bit error (e.g. a script committed without `chmod +x`) — the exact E42_S04 Finding 3 case.
@@ -260,7 +260,7 @@ Append this as a new array entry — never overwrite existing log content. This
 
 **Effect — forced inline scope.** `execution_scope` is force-set to `inline` for any `locked` task, overriding whatever scope `j.jenga`'s Execution Scope Assignment heuristics would otherwise assign — or auto-correcting a wrong value in place, with a logged `override_justification` note. The concrete mechanism is `skills/jenga/SKILL.md` Phase 0.5's **Rule 4 — `crucial_level: locked` forces `execution_scope: inline`** (added by E39_S03_T03). As tester, verify this field is actually `inline` on any `locked` item you're validating — a value that slipped through would itself be a defect worth flagging.
 
-**Effect — dispatch-time rejection of backgrounding.** A `locked` task can never be routed to a background subagent, a worktree-isolated session, or a bundled `j.jenga` story-batch execution, regardless of its `execution_scope` value. This is enforced at two points, both added by E39_S03_T04: `skills/jenga/SKILL.md` Phase 3.5 step 5's **Guard: locked-task disqualifier (defense-in-depth)** and `skills/do/SKILL.md` Section 4.2's **Locked-task dispatch guard (defense-in-depth)**. This matters directly to you as tester: you must never yourself dispatch, recommend, or improvise a background subagent, a separate worktree-isolated session, or a bundled batch run in order to verify a `locked` item faster or in parallel with other work — verification of a `locked` item happens in the same foreground session the guards already pinned it to, same as implementation.
+**Effect — dispatch-time rejection of backgrounding.** A `locked` task can never be routed to a background subagent, a worktree-isolated session, or a bundled `j.jenga` story-batch execution, regardless of its `execution_scope` value. This is enforced at two points, both added by E39_S03_T04: `skills/jenga/SKILL.md` Phase 3.5 step 5's **Guard: locked-task disqualifier (defense-in-depth)** and `skills/j-do/SKILL.md` Section 4.2's **Locked-task dispatch guard (defense-in-depth)**. This matters directly to you as tester: you must never yourself dispatch, recommend, or improvise a background subagent, a separate worktree-isolated session, or a bundled batch run in order to verify a `locked` item faster or in parallel with other work — verification of a `locked` item happens in the same foreground session the guards already pinned it to, same as implementation.
 
 **No agent-discretion obligation.** Unlike `advisory` (a reporting-cadence habit) and `gated` (a confirmation you must actively pause and perform), `locked` requires no judgment call from you. It is fully enforced by pre-flight validation (Rule 4) and dispatch-time guards (the Phase 3.5 and `j.do` guards above) before the developer ever begins work — none of this depends on you noticing or remembering anything mid-verification. Your only obligation is to recognize that a `locked` task always runs (and was always verified) in the current foreground session, and to never suggest or perform a workaround that would route around that guarantee. If you find evidence during verification that a `locked` item was actually run in a backgrounded or worktree-isolated context, treat that as a guard failure worth flagging (see Rapport System), not something to silently pass.
 
@@ -381,7 +381,7 @@ After every status update to a task or story, check whether a parent rollup is w
 
 2. The scrum master processes rollup triggers from the queue at its next session start and updates story and epic statuses accordingly.
 
-**Playbook step status is out of scope for this rollup (E53_S04_T03 audit).** `/jenga` playbook
+**Playbook step status is out of scope for this rollup (E53_S04_T03 audit).** `j.jenga` playbook
 runs (`skills/jenga/scripts/run-playbook-step.sh`) track their own separate step-level status
 vocabulary (`step_ready`/`complete`/`halted`, and per-step `passed`/`failed`/`skipped`) in an
 ephemeral, session-local temp state file — never in `project/board/`. This rollup logic never

package/hooks/on_session_end.sh

@@ -128,8 +128,8 @@ if [ -d "$RAPPORT_DIR" ]; then
   # Uses a portable `while read` loop rather than mapfile/readarray: macOS
   # ships bash 3.2 (no mapfile support), and this hook must run there —
   # matches the convention already established in scripts/smoke-harness.sh,
-  # skills/publish/scripts/generate_release_notes.sh, and
-  # skills/publish/scripts/finalize_changelog.sh. Fixed incidentally here
+  # skills/j-publish/scripts/generate_release_notes.sh, and
+  # skills/j-publish/scripts/finalize_changelog.sh. Fixed incidentally here
   # because this task's acceptance criteria require the hook to actually
   # execute end-to-end (mapfile silently failed on stock macOS bash,
   # leaving CURRENT_FILES empty and masking real detection results).
@@ -312,9 +312,9 @@ for HANDOFF_FILE in "$HANDOFF_DIR"/*.json; do
       # A conversational architecture elicitation session (/uncharted
       # onboard's default flow, or segment --mode investigate — E20_S08_T03)
       # ended mid-run without converging. The session driving it is
-      # responsible for calling skills/uncharted/scripts/elicitation-state.sh
+      # responsible for calling skills/j-uncharted/scripts/elicitation-state.sh
       # pause and then writing this handoff with status "elicitation_paused"
-      # as its last action (see skills/uncharted/SKILL.md's Multi-Session
+      # as its last action (see skills/j-uncharted/SKILL.md's Multi-Session
       # Persistence subsection). This routes that pause into a resume
       # signal for the next scrum-master session, per the existing
       # SessionEnd/queue pattern rather than a new persistence mechanism
@@ -425,4 +425,4 @@ bash "$PROJECT_DIR/scripts/todo_cleanup.sh"
 # digest's consumer is a later session that may not have started yet when
 # THIS session ends — see scripts/sweep-stale-context-digests.sh's header for
 # the full rationale. Runs unconditionally, same as todo cleanup above.
-bash "$PROJECT_DIR/scripts/sweep-stale-context-digests.sh"
+bash "$PROJECT_DIR/scripts/sweep-stale-context-digests.sh"

package/lib/generate-agent-context.js

@@ -5,7 +5,7 @@
  * Single source of truth for scaffolding the two root-level agent-context
  * files from templates/agent-context.md.tpl (E41_S04_T02). Used by:
  *   - lib/commands/init.js         (published `jenga init` CLI)
- *   - skills/init/scripts/init.sh  (this repo's own board-scaffolding flow,
+ *   - skills/j-init/scripts/init.sh  (this repo's own board-scaffolding flow,
  *                                   invoked via `node` — see the CLI guard
  *                                   at the bottom of this file)
  *
@@ -234,7 +234,7 @@ export function generateAgentContext(projectRoot = process.cwd(), packageRoot =
 }
 
 // CLI guard — allows `node lib/generate-agent-context.js [projectRoot]`,
-// used by skills/init/scripts/init.sh (this repo's own board-scaffolding
+// used by skills/j-init/scripts/init.sh (this repo's own board-scaffolding
 // flow, where node is guaranteed available). The published npm CLI path
 // (lib/commands/init.js) imports generateAgentContext() directly instead.
 //

package/lib/generate-copilot-hooks.js

@@ -30,7 +30,7 @@
  * is no legitimate reason for a consumer to hand-edit it, so a full deterministic overwrite on
  * every run is safe and simpler than a marker-merge.
  *
- * No `skills/self-sync/scripts/run.js` wiring is needed either: self-sync mirrors root-level
+ * No `skills/j-self-sync/scripts/run.js` wiring is needed either: self-sync mirrors root-level
  * source directories, and this file has none to mirror — it is generated directly, exactly like
  * `.github/copilot-instructions.md` is (also outside self-sync's `COPY_SET`/`GITHUB_COPY_SET`).
  *

package/lib/generate-skill-allow-list.js

@@ -19,10 +19,26 @@
  * Auto-regeneration at `/self-sync`/postinstall time is wired up separately by the follow-up
  * task E50_S02_T02 — not in scope here.
  *
+ * ## The three-way mapping (E50_S12_T01)
+ *
+ * This generator's correctness rests on a relationship that used to be left implicit in
+ * `extractName`'s regex. Stated explicitly, per `docs/skill-authoring.md`'s "The Canonical Naming
+ * Contract" table (settled 2026-09-09, transcribed from E50_S10):
+ *
+ *   skills/j-<name>/  (directory)  <->  name: j.<name>  (frontmatter)  <->  <name>  (allow-listed
+ *   identifier, after extractName's /^j[.:]/i strip)
+ *
+ * Three permanent exceptions skip the `j-` prefix on all three legs of that mapping and keep their
+ * bare form everywhere: `jenga`, `jenga-permission-level` (both deliberately excluded from twin
+ * generation, E50_S06), and `index` (not a skill — no SKILL.md, not part of routing). Every other
+ * skill under `skills/` is expected to satisfy the mapping above once E50_S15 lands (see that
+ * story's frontmatter-rewrite scope) — see the note below on the transitional state this generator
+ * currently has to tolerate.
+ *
  * Consumers:
  *   - CLI guard at the bottom of this file (`node lib/generate-skill-allow-list.js`) — run once
  *     against this repo's own skills/ to produce the committed lib/skill-allow-list.json, and
- *     intended to be callable from skills/self-sync/scripts/run.js and scripts/postinstall.js in
+ *     intended to be callable from skills/j-self-sync/scripts/run.js and scripts/postinstall.js in
  *     the follow-up task.
  *   - getSkillAllowListIdentifiers() — an in-memory-only helper for callers that want the
  *     identifier list without touching disk, e.g. the MCP router work in E50_S02_T03.
@@ -48,6 +64,24 @@ const DEFAULT_PACKAGE_ROOT = join(__dirname, "..");
  * is needed here (unlike mcp/router/skill-index.js's fuller frontmatter parser, which also
  * handles array fields like `keywords`/`examples`) — a direct regex against the frontmatter
  * block is sufficient and avoids re-implementing that broader parser for a single field.
+ *
+ * This is the function that produces one leg of the three-way mapping described in this file's
+ * header (`directory <-> frontmatter name: <-> allow-listed identifier`): given a SKILL.md's raw
+ * frontmatter `name:` value, it returns the bare identifier that goes into the allow-list. For a
+ * normal skill (post-E50_S15) that value is `j.<name>` and this strips to `<name>`, matching the
+ * `skills/j-<name>/` directory it was read from with the `j-` prefix removed. For the three
+ * permanent exceptions (`jenga`, `jenga-permission-level`, `index`) the frontmatter carries no
+ * prefix at all and this is a no-op, matching their bare directory name directly.
+ *
+ * Transitional note (pre-E50_S15): as of E50_S12, most `skills/j-<name>/SKILL.md` twins still
+ * carry the doubled `name: j.j-<name>` form (E50_S15's frontmatter rewrite to `j.<name>` has not
+ * landed yet — that rewrite and the bare-directory deletion are scoped together and must land in
+ * the same change, per E50_S15's story file). Stripping a single leading `j[.:]` off a doubled
+ * value yields `j-<name>`, not `<name>` — a real, known, and separately-owned gap in the
+ * three-way mapping above, not a bug in this function's own contract. See
+ * `project/documentation/plans/E50_S12-plan.md` for why this task's regression coverage targets a
+ * synthetic twin-only tree (where the mapping already holds) rather than asserting a bijection
+ * against this repo's own transitional `skills/` tree.
  */
 function extractName(content) {
   const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
@@ -116,7 +150,7 @@ export function getSkillAllowListIdentifiers(skillsDir = DEFAULT_SKILLS_DIR) {
 
 /**
  * Read the committed skill-allow-list.json artifact (produced by generateSkillAllowList /
- * regenerated by postinstall.js and skills/self-sync/scripts/run.js) and return its `skills`
+ * regenerated by postinstall.js and skills/j-self-sync/scripts/run.js) and return its `skills`
  * array. Resolution order mirrors resolveTemplatePath's packageRoot-then-projectRoot candidate
  * order in lib/generate-agent-context.js and lib/generate-copilot-instructions.js: the artifact
  * normally lives at `<packageRoot>/lib/skill-allow-list.json` (the installed jenga-agent
@@ -180,7 +214,7 @@ export function generateSkillAllowList(skillsDir = DEFAULT_SKILLS_DIR, outputPat
 }
 
 // CLI guard — allows `node lib/generate-skill-allow-list.js [skillsDir] [outputPath]`, intended
-// to be callable from skills/self-sync/scripts/run.js and scripts/postinstall.js in the
+// to be callable from skills/j-self-sync/scripts/run.js and scripts/postinstall.js in the
 // follow-up auto-regeneration task (E50_S02_T02).
 //
 // process.argv[1] is compared via realpath, not as a raw string — see the identical comment

package/lib/mirror.js

@@ -5,7 +5,7 @@
  * (files or directories) from a source root into a destination root. Used
  * by:
  *   - scripts/postinstall.js  (consumer install; reconcileDeletes = false)
- *   - skills/self-sync/...    (in-repo dev mirror; reconcileDeletes = true)   [wired in T02]
+ *   - skills/j-self-sync/...    (in-repo dev mirror; reconcileDeletes = true)   [wired in T02]
  *
  * Design constraints:
  *   - ESM, Node built-ins only (node:fs / node:fs/promises / node:path).

package/lib/postinstall-manifest.js

@@ -42,7 +42,7 @@
  *     "package_version":  "3.0.1",
  *     "generated_at":     "2026-09-07T00:00:00.000Z",
  *     "dest_root":        ".agents",
- *     "paths":            ["agents/developer.md", "skills/do/SKILL.md"]
+ *     "paths":            ["agents/developer.md", "skills/j-do/SKILL.md"]
  *   }
  *
  *   - `paths` are relative to the destination root, POSIX-separated, deduped and

package/lib/skill-allow-list.json

@@ -1,5 +1,5 @@
 {
-  "generated_at": "2026-09-14T18:42:41.263Z",
+  "generated_at": "2026-09-20T06:12:06.824Z",
   "skill_count": 41,
   "skills": [
     "brainstorm",
@@ -12,7 +12,6 @@
     "dashboard",
     "dashboard-share",
     "deep-dive",
-    "dev-done",
     "distribute",
     "do",
     "doc",
@@ -21,6 +20,7 @@
     "error",
     "evaluate",
     "examplify",
+    "gitignore",
     "help",
     "idea",
     "improve",

package/mcp/help/index.js

@@ -2,8 +2,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { existsSync, readdirSync, statSync } from "fs";
-import { join, resolve } from "path";
+import { resolve } from "path";
+import { resolveSkillsDir, candidateSkillsDirs, listSkillFolders } from "./scan.js";
 
 const server = new McpServer({
   name: "help",
@@ -23,15 +23,13 @@ server.tool(
   },
   async ({ path: inputPath }) => {
     const root = inputPath ? resolve(inputPath) : process.cwd();
-    // The jenga-agent postinstall mirrors skills/ into both .claude/ (Claude Code)
-    // and .agents/ (Copilot / custom agents). Prefer .claude/; fall back to .agents/.
-    const candidates = [
-      join(root, ".claude", "skills"),
-      join(root, ".agents", "skills"),
-    ];
-    const skillsDir = candidates.find(existsSync);
+    // E50_S12_T06: the actual scan logic lives in ./scan.js (resolveSkillsDir /
+    // listSkillFolders) so it is importable and unit-testable without starting this
+    // MCP server. See that module's header for why. No behavior change here.
+    const skillsDir = resolveSkillsDir(root);
 
     if (!skillsDir) {
+      const candidates = candidateSkillsDirs(root);
       return {
         content: [
           {
@@ -42,14 +40,7 @@ server.tool(
       };
     }
 
-    const entries = readdirSync(skillsDir);
-    const folders = entries.filter((entry) => {
-      try {
-        return statSync(join(skillsDir, entry)).isDirectory();
-      } catch {
-        return false;
-      }
-    });
+    const folders = listSkillFolders(skillsDir);
 
     if (folders.length === 0) {
       return {

package/mcp/help/scan.js

@@ -0,0 +1,73 @@
+/**
+ * mcp/help/scan.js — pure directory-scan logic behind the `help` MCP tool (E50_S12_T06).
+ *
+ * Split out of index.js so it is importable and unit-testable without starting an MCP
+ * server. index.js instantiates an `McpServer` and ends with a top-level
+ * `await server.connect(transport)` that blocks on stdin — importing that file as a
+ * whole would hang any test that tried it, the exact untestability
+ * mcp/router/allow-list-guard.js's header describes for mcp/router/index.js, and the
+ * same reason mcp/router's Stage 1 decision was extracted into its own module by
+ * E50_S07_T02. This file mirrors that precedent: plain Node built-ins only, no MCP SDK
+ * import, no side effects at module load time.
+ *
+ * Confirmed by direct reading (E50_S12_T06): this is a pure `readdirSync`/`statSync`
+ * scan. It never parses a SKILL.md's frontmatter, never strips a `j.`/`j:` prefix, and
+ * never compares against the allow-list — it returns whatever directory names exist
+ * under `.claude/skills`/`.agents/skills` verbatim. A `j-<name>` twin directory and a
+ * bare `<name>` directory are both just directory names to this code; neither is
+ * treated differently in any way, so nothing here needs to change for a twin-only tree.
+ */
+
+import { existsSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+
+/**
+ * Resolves which of the two generated skill mirrors exists under `root`. The
+ * jenga-agent postinstall mirrors skills/ into both .claude/ (Claude Code) and
+ * .agents/ (Copilot / custom agents); this prefers .claude/, falling back to .agents/.
+ *
+ * @param {string} root - project root to scan (already resolved to an absolute path)
+ * @returns {string|null} the first candidate skills directory that exists, or null
+ */
+export function resolveSkillsDir(root) {
+  const candidates = [
+    join(root, ".claude", "skills"),
+    join(root, ".agents", "skills"),
+  ];
+  return candidates.find(existsSync) ?? null;
+}
+
+/**
+ * The two candidate mirror paths under `root`, in preference order — exposed
+ * separately from resolveSkillsDir() so a caller can report "looked in: ..." even when
+ * neither candidate exists (mirrors index.js's `help` tool's own "No skills found"
+ * message).
+ *
+ * @param {string} root
+ * @returns {string[]}
+ */
+export function candidateSkillsDirs(root) {
+  return [
+    join(root, ".claude", "skills"),
+    join(root, ".agents", "skills"),
+  ];
+}
+
+/**
+ * Lists the immediate subdirectory names of `skillsDir` — the exact set the `help` tool
+ * reports. See this module's header for why this is safe to call against a twin-only
+ * tree with no code change: it is a verbatim directory listing, format-agnostic.
+ *
+ * @param {string} skillsDir - an existing directory (typically resolveSkillsDir()'s result)
+ * @returns {string[]} immediate subdirectory names, in readdirSync's natural order
+ */
+export function listSkillFolders(skillsDir) {
+  const entries = readdirSync(skillsDir);
+  return entries.filter((entry) => {
+    try {
+      return statSync(join(skillsDir, entry)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jenga-ai/agent",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "description": "An agentic development workflow for Claude Code, Copilot, and Codex — with a persistent Epic/Story/Task board, an isolated git worktree per task, and a separate tester agent that runs your test suite before anything is marked done.",
   "type": "module",
   "publishConfig": {
@@ -12,12 +12,17 @@
   "engines": {
     "node": ">=14.13.1"
   },
+  "jenga": {
+    "requiresLifecycleScripts": true,
+    "note": "postinstall (scripts/postinstall.js) mirrors skills/agents/hooks into the consumer project and is load-bearing for the whole framework install. On package managers that block lifecycle scripts by default (pnpm v10+, npm 11.16+ via allowScripts), an explicit consumer-side opt-in is required — see docs/distribution.md."
+  },
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
     "prepack": "npm run ui:build --prefix project/app --",
     "generate:legacy-paths": "node scripts/generate-legacy-shipped-paths.js",
     "graph:populate": "node scripts/populate-knowledge-graph.js",
     "test": "bats tests/*.bats",
+    "gate:twin-parity": "bash scripts/audit-twin-divergence.sh . --min-pairs 40",
     "validate:npm-metadata": "bash scripts/validate_npm_metadata.sh",
     "ui:dev": "npm run ui:dev --prefix project/app --",
     "ui:build": "npm run ui:build --prefix project/app --",