@jenga-ai/agent 1.3.0 → 3.0.0

package/agents/scrum-master.md

@@ -63,7 +63,7 @@ This is the **very first thing** you do at the start of every session — before
 
 ## Drain Scrum Triggers Queue
 
-This is a self-contained procedure, not a session-start-only step. It may be invoked automatically at session start (see "Session Start — Queue Processing" below) **or** explicitly, mid-session, by another skill — for example `/jenga`'s Phase 4 loop, which runs as one long-lived scrum-master session and needs rollups to happen promptly after each wave of background agent completions rather than waiting for a future session start. Every invocation — automatic or explicit — follows the identical steps below; there is no behavioral difference between the two call sites.
+This is a self-contained procedure, not a session-start-only step. It may be invoked automatically at session start (see "Session Start — Queue Processing" below) **or** explicitly, mid-session, by another skill — for example `j.jenga`'s Phase 4 loop, which runs as one long-lived scrum-master session and needs rollups to happen promptly after each wave of background agent completions rather than waiting for a future session start. Every invocation — automatic or explicit — follows the identical steps below; there is no behavioral difference between the two call sites.
 
 1. **Check `project/queue/scrum_triggers.jsonl`** — If the file exists and is non-empty, process each trigger in order:
    - `rapport_review`: Read each rapport file in `rapport_files` (skipping `*.IGNORE.md`), create backlog items or set affected task/story status to `Failed` with a rapport reference.
@@ -76,7 +76,7 @@ This is a self-contained procedure, not a session-start-only step. It may be inv
        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").
    - `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 `/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.
+   - `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.
    - 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.
@@ -197,6 +197,16 @@ Before writing each task file to `project/board/tasks/`, verify:
 4. `scope_rationale` is specific — not generic filler.
 5. If items 3 or 4 fail, change `execution_scope` to `task` and rewrite `scope_rationale` to reflect that fallback honestly.
 
+### Task-Folding Check
+
+**Before creating a sibling task, verify it has independent work of its own.** This check is required before writing any task file to `project/board/tasks/`, in addition to the Breakdown Checklist above.
+
+Ask: will this deliverable get done anyway as a side effect of an already-planned sibling task in the same story (e.g. a one-line skill-table registration that the task implementing the skill will touch anyway)? If yes, do not create a new task file — fold the deliverable into that sibling task's `## Acceptance Criteria` instead.
+
+**Motivating example:** `E42_S04_T02` ("register `j.dev-done` in `CLAUDE.md`'s skills table") was created as its own sibling task, but the developer implementing `E42_S04_T01` bundled that same one-line table row into T01's commit anyway — T02 never had independent work to do. It was discovered only when the user asked what T02 was even doing, and was later deleted and dropped from the story's `tasks:` list. See `project/rapports/analysis/E42_S04-execution-overhead-postmortem.md`, Finding 4.
+
+This check applies regardless of the sibling task's `execution_scope`.
+
 ---
 
 ## Execution Scope Assignment
@@ -213,6 +223,27 @@ Assign `inline` when **all** of the following are true:
 
 `needs_docs` for every `inline`-scoped task is always `false`.
 
+### `light` scope
+
+`light` sits between `inline` and `task`: a single developer subagent pass with no worktree, self-verified via `scripts/smoke-harness.sh` in lieu of a separate tester invocation. If the smoke harness fails, execution falls back to `task` scope automatically at runtime — see `templates/SCRUM_BOARD_SCHEMA.md`'s Execution Scope Fields section for the full runtime contract.
+
+Assign `light` when **any** of the following are true:
+- The task exceeds `inline_max_files` or `inline_max_lines` (per `project/configs/scope-thresholds.json`), but remains a single, tightly-bounded change (one file, or a small handful of directly related files)
+- The change is purely additive or config-level, like `inline`, but its estimated diff exceeds `inline_max_lines`
+- The task introduces minor branching or a small conditional (not "non-trivial architecture" — that still requires `task`) that would otherwise disqualify it from `inline`, but the change is still self-contained enough to verify with a smoke-harness pass rather than a full tester cycle
+
+**Distinguishing `light` from `inline`:** `light` is for changes too big or too branchy for `inline`'s caps (`inline_max_files`, `inline_max_lines`) — if the change fits within those caps with no logic branches, use `inline` instead.
+
+**Distinguishing `light` from `task`:** assign `light`, not `task`, only when **all** of the following also hold:
+- The task does **not** require worktree isolation — it can be implemented directly by a single developer subagent pass
+- The task does **not** require independent tester verification — a `scripts/smoke-harness.sh` self-check is sufficient to catch regressions
+- No shared-infrastructure contention exists (same contention concept as the `story` scope's mandatory contention check below — e.g. `package.json`, `settings.json`, `pyproject.toml`)
+- The task has no cross-story dependencies and tester validation is not sensitive to the specific implementation approach chosen
+
+If any of the `task`-scope triggers below apply (branching beyond "minor," shared infrastructure, cross-story dependencies, contention, or general uncertainty), do not assign `light` — use `task` instead.
+
+**Fallback rule:** if the evidence for `light` isn't concrete — i.e. you cannot point to a specific reason the task exceeds `inline`'s caps while still being confidently worktree-free and tester-free — default to `task`, exactly as the general Fallback Rule above prescribes. Never assign `light` speculatively.
+
 ### `story` scope
 
 Assign `story` when **all** of the following are true:
@@ -339,12 +370,12 @@ When a request comes in:
 ### 3. Finalizing Items
 Once an item is sufficiently defined:
 - Use the appropriate command to register it on the scrum board:
-  - `/todo` — add a new item
+  - `j.todo` — add a new item
   - `/amend` — update or refine an existing item
-  - `/redo` — scrap and restart an item
+  - `j.redo` — scrap and restart an item
 - **Flag user-action prerequisites** — If the item requires the user to perform any action outside agent scope before or during implementation (e.g. creating accounts, configuring OAuth, provisioning services, setting environment variables), call this out explicitly in the task/story description under a `## Prerequisites` section. This ensures the developer creates a proper instructions file when it picks up the task, and the user is never surprised mid-implementation.
-- **Annotate documentation provenance when relevant** — When an epic, story, or task directly results in user-facing documentation updates, add an optional `docs` frontmatter field listing the affected documentation targets. This powers provenance tracking for the `/doc` skill.
-  - **Purpose:** link board work to documentation files so `/doc` can resolve `last_update` frontmatter from real board history.
+- **Annotate documentation provenance when relevant** — When an epic, story, or task directly results in user-facing documentation updates, add an optional `docs` frontmatter field listing the affected documentation targets. This powers provenance tracking for the `j.doc` skill.
+  - **Purpose:** link board work to documentation files so `j.doc` can resolve `last_update` frontmatter from real board history.
   - **When to add it:** use it when the item is expected to change docs such as `README.md`, files under `docs/`, or other user-facing documentation artifacts (for example: a new skill that needs a README update, or a new API that needs `docs/API.md`).
   - **How to populate it:** use repo-relative paths from the repository root, e.g. `docs: ["README.md", "docs/API.md"]`.
   - **Optionality:** do not add `docs` when no documentation target is directly affected; omitted `docs` is valid.
@@ -373,7 +404,7 @@ Before writing any new or amended story file to `project/board/stories/`, valida
 This gate applies to **all story creation and amendment operations** — no story file may be written to the board without passing all three checks.
 
 #### Triggering the Developer
-When board items are committed **and the user intends them for immediate implementation**, write a session handoff file to `project/queue/handoffs/scrum-master-<session_id>-<task_id>.json` — a unique path keyed by this session, not the old shared `project/queue/.session_handoff.json` slot, so that a session ending close to another agent's session can never clobber its handoff. Use the first entry of `task_ids` as `<task_id>` in the filename (or the literal string `batch` if `task_ids` is empty). `on_session_end.sh` forwards the work to the developer queue:
+When board items are committed **and the user intends them for immediate implementation**, write a session handoff file to `project/queue/handoffs/scrum-master-<session_id>-<task_id>.json` — a unique path keyed by this session, not the old shared `project/queue/.session_handoff.json` slot, so that a session ending close to another agent's session can never clobber its handoff. Use the first entry of `task_ids` as `<task_id>` in the filename (or the literal string `batch` if `task_ids` is empty). Before writing the handoff, compose a short `resolved_context` digest of what was already resolved during breakdown for this task — which `templates/SCRUM_BOARD_SCHEMA.md` fields apply, which skill precedent governs, which epic/story-placement decisions were already made — and persist it by calling `scripts/write-context-digest.sh --agent scrum-master --session-id <session_id> --task-id <task_id>` with that content (stays under the ~100-line/few-hundred-token cap defined in `templates/SCRUM_BOARD_SCHEMA.md`'s `resolved_context` subsection; the script rejects oversized input rather than truncating it). Place the script's returned path in the handoff's `resolved_context` field. `on_session_end.sh` forwards the work to the developer queue:
 
 ```json
 {
@@ -383,10 +414,13 @@ When board items are committed **and the user intends them for immediate impleme
   "task_ids": ["<E##_S##_T##>", "..."],
   "story_id": "<E##_S##>",
   "epic_id": "<E##>",
+  "resolved_context": "<path returned by scripts/write-context-digest.sh, or omit if no digest was written>",
   "date": "<ISO 8601 UTC timestamp>"
 }
 ```
 
+This digest is a starting point only, never a restriction: the developer may and should still read the full `templates/SCRUM_BOARD_SCHEMA.md`, relevant skill docs, or `CLAUDE.md` when the digest doesn't cover what it needs.
+
 If the user wants to defer implementation (e.g., brainstorming only, or items are backlogged for later), do **not** write the handoff file.
 
 ### 4. Definition of Done
@@ -407,7 +441,7 @@ If the user wants to defer implementation (e.g., brainstorming only, or items ar
 
 ## Brainstorm Mode
 
-When invoked via the `/brainstorm` skill, switch into **Brainstorm Mode**. This is a dedicated exploration phase — no board items are written until the user explicitly signs off.
+When invoked via the `j.brainstorm` skill, switch into **Brainstorm Mode**. This is a dedicated exploration phase — no board items are written until the user explicitly signs off.
 
 In Brainstorm Mode, amplify the following behaviours:
 
@@ -454,28 +488,28 @@ Clarifications, follow-up details, and edge cases that serve the current story a
 When you detect a divergence, stop advancing the current thread and present the structured choice below. Use a calm, neutral tone — the goal is to keep the user in control, not to interrupt them:
 
     It looks like we're moving into a new topic. How would you like to handle it?
-    1. Capture the **new topic** as a `/todo` (I'll return to what we were working on)
-    2. Capture the **current topic** as a `/todo` (I'll continue with the new topic)
-    3. Capture **both** as `/todo` items (you choose which to continue first)
+    1. Capture the **new topic** as a `j.todo` (I'll return to what we were working on)
+    2. Capture the **current topic** as a `j.todo` (I'll continue with the new topic)
+    3. Capture **both** as `j.todo` items (you choose which to continue first)
     4. Ignore it — tell me which topic to continue with
 
 ### Option A — Capture the Diverging Topic
-1. Draft a `/todo` for the diverging topic. Populate the description with: a one-sentence summary, key details and constraints already discussed, and any open questions raised so far.
-2. Before finalising, offer `/brainstorm` to fill in any missing **Prerequisites** (e.g. third-party accounts, environment setup, external approvals).
-3. Once the `/todo` is saved, return to the primary story/epic context exactly where it was paused.
+1. Draft a `j.todo` for the diverging topic. Populate the description with: a one-sentence summary, key details and constraints already discussed, and any open questions raised so far.
+2. Before finalising, offer `j.brainstorm` to fill in any missing **Prerequisites** (e.g. third-party accounts, environment setup, external approvals).
+3. Once the `j.todo` is saved, return to the primary story/epic context exactly where it was paused.
 
 ### Option B — Capture the Primary Topic
-1. Draft a `/todo` for the primary topic using the same context-surfacing approach: summary, details, open questions.
-2. Offer `/brainstorm` to fill in missing Prerequisites before finalising.
-3. Once the `/todo` is saved, pivot to the diverging topic.
+1. Draft a `j.todo` for the primary topic using the same context-surfacing approach: summary, details, open questions.
+2. Offer `j.brainstorm` to fill in missing Prerequisites before finalising.
+3. Once the `j.todo` is saved, pivot to the diverging topic.
 
 ### Option C — Capture Both
-1. Create a `/todo` for the diverging topic (context summary + Prerequisites offer).
-2. Create a `/todo` for the primary topic (context summary + Prerequisites offer).
+1. Create a `j.todo` for the diverging topic (context summary + Prerequisites offer).
+2. Create a `j.todo` for the primary topic (context summary + Prerequisites offer).
 3. Ask the user which topic to continue first.
 
 ### Context Surfacing
-Every `/todo` created through this flow must include in its description:
+Every `j.todo` created through this flow must include in its description:
 - A one-sentence summary of the topic
 - Key details, constraints, or decisions already discussed
 - Open questions or unknowns raised so far
@@ -483,8 +517,8 @@ Every `/todo` created through this flow must include in its description:
 This is non-negotiable — it is the mechanism that prevents context loss.
 
 ### Edge Cases
-- **User declines both options (selects "Ignore it")**: Do not create any `/todo` items. Acknowledge briefly, then ask which topic to continue. Follow the user's direction without pressure.
-- **User wants to pursue both in parallel**: Treat as Option C — create both `/todo` items with full context summaries, then ask which to continue first.
+- **User declines both options (selects "Ignore it")**: Do not create any `j.todo` items. Acknowledge briefly, then ask which topic to continue. Follow the user's direction without pressure.
+- **User wants to pursue both in parallel**: Treat as Option C — create both `j.todo` items with full context summaries, then ask which to continue first.
 ---
 
 ## Mediator Mode
@@ -495,7 +529,7 @@ Activate Mediator Mode whenever the user is working on AI/ML model setup, traini
 - User asks which model architecture to use
 - User needs help choosing training hyperparameters or a framework
 - User wants to understand model evaluation results
-- User is about to run or configure a training job via the `/train` skill
+- User is about to run or configure a training job via the `j.train` skill
 
 You do not need explicit instruction to enter Mediator Mode — detect the context and activate it automatically.
 

package/agents/tester.md

@@ -155,7 +155,7 @@ When invoked to implement and/or run tests:
    e. Only after all DoD checkboxes are ticked (`- [x]`) may you proceed to step 7.
 7. Evaluate results and set the scrum board status accordingly (see Status Management)
 8. Trigger epic/story rollup if applicable (see Rollup Logic)
-9. If there are unresolved findings, write a test rapport (see Rapport System)
+9. If there are unresolved findings, write a test rapport (see Rapport System) — **unless** the finding is clearly mechanical, in which case fix it in place instead; see "Trivial-Fix-Path (mechanical issues)" below before defaulting to a rapport.
 10. Report back with one of:
     - `"passed"` — all tests passed, no findings
     - `"passed with remarks"` — tests passed but findings exist; reference the rapport
@@ -163,6 +163,52 @@ When invoked to implement and/or run tests:
 
 Always include the sender object in the response.
 
+### Trivial-Fix-Path (mechanical issues)
+
+**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.
+
+**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.
+- An unreachable/dead code branch that you have **directly exercised and confirmed dead** (not merely suspected) — e.g. an error-handling branch whose triggering condition can never occur given the surrounding logic, verified by tracing the actual call path, as in the second half of the E42_S04 Finding 3 case.
+- A pure formatting slip with no behavior change — stray whitespace, a missing trailing newline, a lint-only violation that doesn't alter what the code does.
+
+**Disqualifying examples (still needs a rapport — unaffected by this section).**
+- Anything touching business logic — a conditional, a calculation, a control-flow change that affects output.
+- Anything security-sensitive — auth, permissions checks (beyond a bare file-mode bit), input validation, secret handling.
+- Anything touching data handling — persistence, migrations, data shape, serialization.
+- Anything touching the shape of a public API, schema, or frontmatter contract.
+- Anything requiring a judgment call about what the intended behavior actually is — if you have to guess at intent to decide the "right" fix, it is not mechanical.
+
+When in doubt, treat the defect as disqualifying. The bar for "mechanical" is narrow on purpose — this path is an exception carved out of the rapport system, not a replacement for it.
+
+**In-place fix mechanism.** Make the minimal fix directly in the worktree you are verifying, and commit it there. This follows the same rule already established in "Verification commit target" below: the commit lands on the branch under verification, in that task's worktree, never on `main` or any other branch — confirm with `git branch --show-current` before committing, same as any other verification-time commit. Use the same commit message convention used elsewhere in this file for verification-time fixes, e.g. `chore(<E##_S##_T##>): trivial fix — <short description>`.
+
+**Audit trail.** A qualifying fix is never silent, even though no rapport is filed. Do both of the following:
+1. Append an event to `project/logs/events.json` with this shape, consistent with the file's existing `advisory_checkpoint`/`tool_approval` event shapes:
+
+```json
+{
+  "event": "trivial_fix",
+  "agent": "tester",
+  "session_id": "<current session id>",
+  "task_id": "<E##_S##_T##>",
+  "story_id": "<E##_S##>",
+  "epic_id": "<E##>",
+  "commit_sha": "<sha of the in-place fix commit>",
+  "issue": "<what was found, e.g. 'missing chmod +x on scripts/foo.sh'>",
+  "note": "<one-line justification for why this qualifies as mechanical>",
+  "date": "<ISO 8601 UTC timestamp>"
+}
+```
+
+2. Include a one-line note about the fix in whatever status/commit output you produce for this task (step 10's report, and the status note recorded per Status Management), so the fix is visible even to someone who never opens `events.json`.
+
+**No rapport, no rework.** A qualifying trivial fix does **not** trigger a `test_failure` rapport and does **not** trigger a developer rework cycle. Verification simply continues from where it left off — proceed to step 7 (status evaluation) as if the defect had not blocked anything, with the fix itself noted per the audit trail above. Do not pause, do not hand back to the developer, do not wait for confirmation.
+
+**No regression for anything else.** Anything that doesn't clearly qualify — including anything you're unsure about — is completely unaffected by this section: it goes through the existing rapport → rework cycle exactly as documented in "Test rapports (unresolved findings)" below, unchanged.
+
 ### Crucial Tier: `advisory`
 
 **Trigger.** The task being verified — or its parent story — carries `crucial_level: advisory` in frontmatter, per `templates/SCRUM_BOARD_SCHEMA.md`'s "Crucial Flag Fields (Story, Task)" section.
@@ -212,11 +258,11 @@ Append this as a new array entry — never overwrite existing log content. This
 
 **Trigger.** The task being verified — or its parent story — carries `crucial_level: locked` in frontmatter, per `templates/SCRUM_BOARD_SCHEMA.md`'s "Crucial Flag Fields (Story, Task)" section.
 
-**Effect — forced inline scope.** `execution_scope` is force-set to `inline` for any `locked` task, overriding whatever scope `/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 — 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 `/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/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 `/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.
+**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.
 
 ### Invoked for analysis or comparison testing
 When invoked to run an analysis or comparison:
@@ -409,7 +455,7 @@ There is no default analytics run. Analytics only happen when explicitly scoped
 
 ## Investigative Mode
 
-**Trigger.** You are sometimes dispatched not to validate a task's implementation, but purely to build understanding of what the existing test suite actually covers for a named flow or target — e.g. by the scrum-master during `/uncharted`'s conversational architecture elicitation, alongside the developer's Investigative Mode pass over the same flow. This is a distinct dispatch mode from the standard Sender Object / Task Intake / Status Management flow above, recognized by the request itself (you are asked to *trace coverage*, not to *validate a task*), not by any board field.
+**Trigger.** You are sometimes dispatched not to validate a task's implementation, but purely to build understanding of what the existing test suite actually covers for a named flow or target — e.g. by the scrum-master during `j.uncharted`'s conversational architecture elicitation, alongside the developer's Investigative Mode pass over the same flow. This is a distinct dispatch mode from the standard Sender Object / Task Intake / Status Management flow above, recognized by the request itself (you are asked to *trace coverage*, not to *validate a task*), not by any board field.
 
 **Hard constraints.** Investigative Mode is strictly read-only:
 - No worktree is created for write purposes, no test files are written or modified, no test runs that mutate state, no dependency installs.

package/hooks/on_session_end.sh

@@ -413,4 +413,16 @@ done
 # --- 5. Todo cleanup ---
 # Remove project/todo.md if it is effectively empty (only blanks, # Todo, and HTML comments).
 # Runs unconditionally on every session end regardless of agent type.
-bash "$PROJECT_DIR/scripts/todo_cleanup.sh"
+bash "$PROJECT_DIR/scripts/todo_cleanup.sh"
+
+# --- 6. Stale resolved_context digest sweep (E49_S01_T02) ---
+# Backstop cleanup for project/queue/context/ digest files. The primary
+# cleanup path is scripts/consume-context-digest.sh, called by the receiving
+# subagent once it has read its digest — this sweep only catches a digest
+# whose intended receiver never consumed it (abandoned dispatch, or a
+# receiver that read the raw file directly and forgot to delete it). Age-based
+# rather than routed-and-deleted-immediately like section 4 above, because a
+# 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"

package/lib/generate-agent-context.js

@@ -29,6 +29,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, realpathSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { readSkillAllowList } from "./generate-skill-allow-list.js";
 
 // This file lives at <package>/lib/generate-agent-context.js — one level up
 // is the installed jenga-agent package root, which holds templates/.
@@ -76,6 +77,20 @@ function buildSkillList(projectRoot) {
   return skillLines.length > 0 ? skillLines.join("\n") : "_No skills found._";
 }
 
+/**
+ * Build the rendered {{ALLOWED_SKILL_IDS}} block: the canonical, committed
+ * `lib/skill-allow-list.json` artifact (E50_S02_T01/T02), rendered as a
+ * compact comma-joined inline-code list for the "Skill Identifier
+ * Allow-List" section of the generated context files (E50_S02_T04). Reads
+ * via the shared readSkillAllowList() helper — never re-derives its own
+ * scan of skills/, so this list always matches the artifact the MCP router
+ * (E50_S02_T03) and postinstall/self-sync regeneration also read from.
+ */
+function buildAllowedSkillIds(projectRoot, packageRoot) {
+  const ids = readSkillAllowList(projectRoot, packageRoot);
+  return ids.length > 0 ? ids.map((id) => `\`${id}\``).join(", ") : "_No skills found._";
+}
+
 function resolveTemplatePath(projectRoot, packageRoot) {
   const candidates = [
     join(packageRoot, "templates", "agent-context.md.tpl"),
@@ -167,13 +182,15 @@ export function generateAgentContext(projectRoot = process.cwd(), packageRoot =
 
   const tpl = readFileSync(tplPath, "utf8");
   const skillList = buildSkillList(projectRoot);
+  const allowedSkillIds = buildAllowedSkillIds(projectRoot, packageRoot);
   const written = [];
 
   for (const target of TARGETS) {
     const rendered = tpl
       .split("{{TARGET_FILENAME}}").join(target.filename)
       .split("{{SKILL_DISCOVERY_PATH}}").join(target.skillDiscoveryPath)
-      .split("{{SKILL_LIST}}").join(skillList);
+      .split("{{SKILL_LIST}}").join(skillList)
+      .split("{{ALLOWED_SKILL_IDS}}").join(allowedSkillIds);
 
     const targetPath = join(projectRoot, target.filename);
     const jFilename = `J-${target.filename}`;

package/lib/generate-copilot-instructions.js

@@ -33,6 +33,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { readSkillAllowList } from "./generate-skill-allow-list.js";
 
 // This file lives at <package>/lib/generate-copilot-instructions.js — one level up is the
 // installed jenga-agent package root, which holds templates/.
@@ -72,6 +73,19 @@ function buildSkillList(skillsDir) {
   return skillLines.length > 0 ? skillLines.join("\n") : "_No skills found._";
 }
 
+/**
+ * Build the rendered {{ALLOWED_SKILL_IDS}} block: the canonical, committed
+ * `lib/skill-allow-list.json` artifact (E50_S02_T01/T02), rendered as a compact comma-joined
+ * inline-code list for the "Routing decision table" allow-list check (E50_S02_T04). Reads via
+ * the shared readSkillAllowList() helper — never re-derives its own scan of a skills
+ * directory, mirroring the sibling buildAllowedSkillIds in lib/generate-agent-context.js so
+ * both routing paths share the one committed artifact.
+ */
+function buildAllowedSkillIds(projectRoot, packageRoot) {
+  const ids = readSkillAllowList(projectRoot, packageRoot);
+  return ids.length > 0 ? ids.map((id) => `\`${id}\``).join(", ") : "_No skills found._";
+}
+
 /**
  * Replace only the JENGA:START..JENGA:END block in an existing copilot-instructions.md with the
  * freshly rendered one, preserving everything outside the markers. If no existing file, write
@@ -129,7 +143,10 @@ export function generateCopilotInstructions(
     ? (skillsDir.startsWith("/") ? skillsDir : join(projectRoot, skillsDir))
     : undefined;
   const skillList = buildSkillList(resolvedSkillsDir);
-  const rendered = tpl.replace("{{SKILL_LIST}}", skillList);
+  const allowedSkillIds = buildAllowedSkillIds(projectRoot, packageRoot);
+  const rendered = tpl
+    .replace("{{SKILL_LIST}}", skillList)
+    .replace("{{ALLOWED_SKILL_IDS}}", allowedSkillIds);
 
   const githubDir = join(projectRoot, ".github");
   const copilotInstructionsPath = join(githubDir, "copilot-instructions.md");

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

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * lib/generate-skill-allow-list.js — canonical skill allow-list generator
+ *
+ * Single source of truth for the `j:`-prefix anti-masquerading guard (E50_S02). Scans a skills
+ * directory for every `<name>/SKILL.md`, extracts each one's canonical `name:` frontmatter
+ * identifier, and writes a sorted, de-duplicated JSON artifact to `lib/skill-allow-list.json`.
+ *
+ * Why this exists: E50_S02's guard checks whether a `j:`-prefixed invocation matches a known
+ * list of genuine Jenga skill identifiers before treating it as trusted (see
+ * docs/skill-authoring.md's "Threat Model — the j: Allow-List Guard" section, landed by
+ * E50_S02_T05, for the guard's exact scope boundary). Every routing path that enforces that
+ * guard — the MCP router (E50_S02_T03) and native/prose routing enforcement (E50_S02_T04) — must
+ * read from this single artifact rather than re-deriving its own scan of `skills/`, mirroring the
+ * drift lesson already documented in E41_S04 (CLAUDE.md and AGENT.md hand-maintained skill lists
+ * had already drifted from each other before that epic unified them onto one generator).
+ *
+ * This module only builds the generator and produces the one-time committed artifact.
+ * Auto-regeneration at `/self-sync`/postinstall time is wired up separately by the follow-up
+ * task E50_S02_T02 — not in scope here.
+ *
+ * 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
+ *     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.
+ *
+ * ESM, Node built-ins only — mirrors lib/generate-agent-context.js and
+ * lib/generate-copilot-instructions.js.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, realpathSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// This file lives at <package>/lib/generate-skill-allow-list.js — one level up is the repo/
+// package root, which holds skills/.
+const DEFAULT_SKILLS_DIR = join(__dirname, "..", "skills");
+const DEFAULT_OUTPUT_PATH = join(__dirname, "skill-allow-list.json");
+const DEFAULT_PACKAGE_ROOT = join(__dirname, "..");
+
+/**
+ * Extract the `name:` frontmatter field from a SKILL.md's content. Only the scalar `name` field
+ * 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.
+ */
+function extractName(content) {
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return null;
+  const nameMatch = fmMatch[1].match(/^name:\s*(.+)$/m);
+  if (!nameMatch) return null;
+  const rawName = nameMatch[1].trim().replace(/^["']|["']$/g, "");
+  // Frontmatter may carry the pre-E50_S01 bare form, the E50_S01 "j:<name>" form, or the
+  // current "j.<name>" form (E50_S07_T01 swapped the separator because GitHub Copilot CLI
+  // rejects ":" in a skill name) — strip whichever prefix is present so the allow-list always
+  // holds bare identifiers, matching mcp/router/skill-index.js's `bareName` handling.
+  //
+  // Both separators must stay accepted: this guard is the E50_S02 anti-masquerading check, and
+  // a normalizer that fails to strip silently populates the allow-list with prefixed entries
+  // ("j.brainstorm" instead of "brainstorm"), which no longer match what the guard compares
+  // against. That is a security-guard failure, not a cosmetic one.
+  return rawName.replace(/^j[.:]/i, "");
+}
+
+/**
+ * Scan `skillsDir` for every immediate `<name>/SKILL.md` and return a sorted, de-duplicated
+ * array of canonical skill identifiers (the frontmatter `name` value, treated as authoritative
+ * per docs/skill-authoring.md's "name must match the directory name" authoring rule — this
+ * function does not itself verify that match, only that `name` is present).
+ *
+ * A SKILL.md missing the `name` field is skipped with a warning, not fatal — mirrors
+ * mcp/router/skill-index.js's buildSkillIndex warning behavior for consistency across the two
+ * scanners.
+ *
+ * No disk write. Pure in-memory scan, for callers (e.g. the MCP router, E50_S02_T03) that want
+ * the identifier list without reading the generated artifact.
+ *
+ * @param {string} skillsDir - directory to scan (default: this repo/package's own skills/)
+ * @returns {string[]} sorted, de-duplicated skill identifiers
+ */
+export function getSkillAllowListIdentifiers(skillsDir = DEFAULT_SKILLS_DIR) {
+  if (!existsSync(skillsDir)) return [];
+
+  const identifiers = new Set();
+
+  for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+
+    const skillMdPath = join(skillsDir, entry.name, "SKILL.md");
+    if (!existsSync(skillMdPath)) continue;
+
+    let content;
+    try {
+      content = readFileSync(skillMdPath, "utf8");
+    } catch (e) {
+      process.stderr.write(`Warning: failed to read ${skillMdPath}: ${e.message} — skipped\n`);
+      continue;
+    }
+
+    const name = extractName(content);
+    if (!name) {
+      process.stderr.write(`Warning: ${skillMdPath} has no 'name' in frontmatter — skipped\n`);
+      continue;
+    }
+
+    identifiers.add(name);
+  }
+
+  return [...identifiers].sort();
+}
+
+/**
+ * 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`
+ * 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
+ * package's own committed copy), with `<projectRoot>/lib/skill-allow-list.json` as a fallback
+ * for the case where this repo IS the project (e.g. this monorepo's own dogfood run).
+ *
+ * This is the single read path both E50_S02_T04 generators (native Claude Code context files
+ * and Copilot/Codex prose-routing instructions) use to render the "trusted identifiers" list —
+ * neither one re-derives its own scan of skills/, per the drift lesson already documented in
+ * E41_S04 and referenced in this module's header comment.
+ *
+ * @param {string} projectRoot - project root directory
+ * @param {string} packageRoot - installed jenga-agent package root (default: this module's own
+ *   package root)
+ * @returns {string[]} the artifact's `skills` array, or [] if the artifact is missing/unparseable
+ */
+export function readSkillAllowList(projectRoot, packageRoot = DEFAULT_PACKAGE_ROOT) {
+  const candidates = [
+    join(packageRoot, "lib", "skill-allow-list.json"),
+    join(projectRoot, "lib", "skill-allow-list.json"),
+  ];
+  const path = candidates.find(existsSync);
+  if (!path) return [];
+
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return Array.isArray(parsed.skills) ? parsed.skills : [];
+  } catch (e) {
+    process.stderr.write(`Warning: failed to read/parse ${path}: ${e.message} — treating allow-list as empty\n`);
+    return [];
+  }
+}
+
+/**
+ * Generate the canonical skill allow-list artifact at `outputPath`.
+ *
+ * The `skills` array is deterministic — sorted and de-duplicated, so repeat runs with no
+ * `skills/` change produce a byte-identical array. `generated_at` is NOT deterministic (it is a
+ * fresh timestamp on every run) — that is expected and intentional, not a bug: only the `skills`
+ * array itself is contracted to be stable.
+ *
+ * @param {string} skillsDir - directory to scan (default: this repo/package's own skills/)
+ * @param {string} outputPath - where to write the JSON artifact (default: lib/skill-allow-list.json)
+ * @returns {{written: boolean, path: string, skill_count: number}}
+ */
+export function generateSkillAllowList(skillsDir = DEFAULT_SKILLS_DIR, outputPath = DEFAULT_OUTPUT_PATH) {
+  const skills = getSkillAllowListIdentifiers(skillsDir);
+
+  const artifact = {
+    generated_at: new Date().toISOString(),
+    skill_count: skills.length,
+    skills,
+  };
+
+  const outDir = dirname(outputPath);
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+
+  writeFileSync(outputPath, JSON.stringify(artifact, null, 2) + "\n", "utf8");
+
+  return { written: true, path: outputPath, skill_count: skills.length };
+}
+
+// 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
+// follow-up auto-regeneration task (E50_S02_T02).
+//
+// process.argv[1] is compared via realpath, not as a raw string — see the identical comment
+// block in lib/generate-agent-context.js for why: Node resolves import.meta.url through symlinks
+// when loading an ES module, but leaves process.argv[1] exactly as the shell passed it, so an
+// invocation from a path under a symlinked directory (e.g. macOS's /tmp -> /private/tmp) would
+// otherwise silently fail this comparison and skip generation with no error.
+const invokedPath = process.argv[1] ? realpathSync(process.argv[1]) : null;
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  const skillsDirArg = process.argv[2] || DEFAULT_SKILLS_DIR;
+  const outputPathArg = process.argv[3] || DEFAULT_OUTPUT_PATH;
+  const result = generateSkillAllowList(skillsDirArg, outputPathArg);
+  console.log(`✓ ${result.path} (${result.skill_count} skills)`);
+}

package/lib/skill-allow-list.json

@@ -0,0 +1,42 @@
+{
+  "generated_at": "2026-09-06T15:53:37.575Z",
+  "skill_count": 36,
+  "skills": [
+    "brainstorm",
+    "btw",
+    "clearify",
+    "close-story",
+    "commit",
+    "continue",
+    "deep-dive",
+    "dev-done",
+    "distribute",
+    "do",
+    "doc",
+    "doc-sync",
+    "dooo",
+    "error",
+    "evaluate",
+    "examplify",
+    "help",
+    "idea",
+    "improve",
+    "init",
+    "jbp",
+    "jenga",
+    "jenga-permission-level",
+    "lgtm",
+    "pi-plan",
+    "proceed",
+    "publish",
+    "reconcile",
+    "reconcile-origin",
+    "redo",
+    "skillify",
+    "spinoff",
+    "status",
+    "todo",
+    "uncharted",
+    "wtf"
+  ]
+}